Skip to content

Simulation Configuration

Jump to bottom
smart-fm edited this page Nov 9, 2018 · 5 revisions

The simulation.xml file is a common configuration file for short-term and mid-term. The user can configure the following settings in this file:

  • Database connection information from where the network and demand is loaded
  • Login credentials for the database
  • Simulation start time, end time and granularity
  • Percentage of drivers using in-simulation travel time
  • Strategy to add new agents to workers
  • Mutual exclusion (multi threading) method
  • Driver behaviour file

The file is grouped into three XML elements, viz.

  • constructs
  • simulation
  • generic props

constructs

The database connection and login credential settings are grouped under constructs tag.

<constructs>
    <databases>
        ...
        ...
    </databases>
    <credentials>
        ...
        ...
    </credentials>
</constructs>

Database connections

The user can configure multiple database connections in this section. The databases tag can hold a list of database elements. Each database element holds the connection settings for a single database. Each database tag must have a different value for the id attribute which is used to uniquely identify that database. The structure of a database element within databases is shown below.

<databases>      
     <database id="<user_defined_id>" dbtype="<type_of_database>"/>    
         <host value="<ip_address_value>"/>     
         <port value="<port_number>"/>    
         <dbname value="<name_of_the_database>"/>    
     </database>    
.       
.            
</databases>

Database login credentials

Each database element contains only host, port and database name. The login credentials are kept separate under credentials. The credentials can either be passed in plain-text or file-based formats. The structure of the child elements are explained below. Any number of plain-text and file-based credentials can be configured within credentials. However, similar to database elements, each credential element must have a unique value for the id attribute.

plain-text
<credentials>      
     <plaintext-credential id="<user_defined_id>">    
         <username value="<user_name>"/>   
         <password value="<password>"/> 	 
     </plaintext-credential>      
.
.
.
</credentials>
file-based:
<credentials>   
     <file-based-credential id="<user_defined_id>">    
          <file path="<path_of_the_file>"/>        
     </file-based-credential>        
</credentials>

The file-based credentials are loaded from a JSON file. It is possible to specify more than one file in a single configuration, in this case the simulator will use the first matching file. File based credentials allow us to encrypt the database password to keep it confidential.

The credential file format is as follows.

{ 
    "username" : "<user_defined_name>",   
    "password" : "<encrypted_password>",     
    "algorithm" : "<algorithm>"       
}

simulation

This section contains the settings for simulation start time, run time, warm up time, granularity (simulation step size), strategy for assigning agents to workers and mutual exclusion method.

<simulation>   
     <base_granularity value="100" units="ms"/>       
     <total_runtime value="20" units="minutes"/>      
     <total_warmup value="10" units="seconds"/>        
     <start_time value="10:00:00"/>     
     <workgroup_assignment value="roundrobin"/>       
     <mutex_enforcement strategy="buffered"/>           
     <auto_id_start value="0"/>        
</simulation>
  • base_granularity: The step size in which the total runtime is divided and processed. The granularity is filled in the value tag and unit is specified in units tag. The minimum step size is 100ms (milliseconds) for short-term and usually 5 seconds for mid-term.
  • total_runtime: Total runtime of the simulation. The runtime is filled in the 'value' tag and unit is specified in the units tag
  • total_warmup: The total time at the start of the simulation where the statistics are not collected. Currently, this feature is not available. The time is filled in the value tag and unit is specified in the units tag
  • start_time: Start time of the simulation. It is given in HH:MM:SS format. The start time is specified in the value tag
  • in_simulation_travel_time_usage: Specify the percentage of drivers that use the in-simulation travel time rather than the historical travel time. The drivers will be picked based on uniform distribution. The percentage is specified in the value tag
  • workgroup_assignment: The mode in which the agents are assigned to different workers (threads). Currently, SimMobility supports two modes.
    1. roundrobin: Assigns the agents to workers in order
    2. smallest: Assigns the agents to a worker which manages the least number of agents at the time of the assignation. At the moment this mode doesn't offer better performance than roundrobin method
      The option is filled in value tag
  • mutex_enforcement: The method in which the mutual exclusion is handled to synchronise different workers (threads) at each time step. Currently, SimMobility supports two modes.
    1. buffered: Variable values are changed locally (at agent level) and synchronized at the end of each time step
    2. locked: Variables are guarded with a lock when making a change buffered gives better performance and it is the default option. The option in filled in strategy tag
  • auto_id_start: Internally, each agent created in the simulation has a given id. The starting value of the id-s should be filled in the value tag

generic_props

This section can be used by developers to quickly add configuration for testing new features. This section is used to contain the configuration to locate the driver behaviour file for short-term.

<generic_props>   
     <property key="driver_behaviour_file" value="data/driver_behavior_model/driver_param.xml"/>             
</generic_props>

The driver_behaviour_file parameter specifies the location of the file which holds the driver behaviour parameter settings. This file is explained in detail in the [Parameter] (https://github.com/smart-fm/simmobility-prod/wiki/Short-Term-Parameters) section.

Clone this wiki locally