example_config.yaml

# This is an example configuration file for Si.T.T.
# It demonstrates how to set all the existing variables to make your simulation work.

# Note that command line arguments override the values set in the configuration file. This makes it easier to change the
# behavior of your simulation without having to edit your configuration file.

# You can define some values dynamically, e.g. to keep secrets out of your config file. In order to do this, use the
# YAML tag !Env as prefix of the values.
#
# Example:
# args:
#   myvalue: normal value
#   mysecret: !Env "${SUPERSECRET}"
#
# Pass SUPERSECRET as environment variable to python to set this value. This also works for multiple strings like:
# "Hello ${PLANET}! How are ${ADDRESS}?"
#
# Moreover, you can define YAML variables using & and *. See &psql_port example below.

########################################################################################################################
# runtime configuration

# verbose output/logging
verbose: false
# suppress output/logging - will override quiet of set to true
quiet: false

# Skip certain steps in the simulation. Allowed values are none, simulation, output.
# Naturally, setting the value to simulation will also skip the output.
#skip_step: none

# The following shorthands can be set, too:
#skip_simulation: false
#skip_output: false

# break simulation step after this number of iterations, defaults to 100
# break_simulation_after: 100

# Simulation start and end points
simulation_start: &simulation_start START_HUB_ID
simulation_end: &simulation_end END_HUB_ID

# used as global start date (e.g. in nc files), must be ISO date YYYY-MM-DD
start_date: &start_date 1990-08-01

########################################################################################################################
# variables to use below - variables are normal YAML variables prefixed with &node anchors and aliased using *
# example:
# define using:
#   psql_server: &psql_server 127.0.0.1
# later use like this:
#   server: *psql_server
variables:
  psql_port: &psql_port 5432

########################################################################################################################
# settings to use below
settings:
  connections:
    # source connections can be defined here, so you do not have to add these repeatedly below.
    # Here is an example of a PostgreSQL connection setting used for PsqlReadPathsAndHubs and PsqlSavePathsAndHubs.
    # It takes both environment variables (defined by YAML tags) and YAML node anchors.
    # In our example the following environment variables are considered to be set:
    # PSQL_SERVER=127.0.0.1
    # PSQL_DB=sitt
    # PSQL_PASSWORD=supersecret
    # PSQL_USER=postgres
    psql_default:
      # Connection data for Postgres
      server: !Env "${PSQL_SERVER}"
      port: *psql_port
      db: !Env "${PSQL_DB}"
      user: !Env "${PSQL_USER}"
      password: !Env "${PSQL_PASSWORD}"
      # schema name - where are the tables saved in?
      schema: sitt

########################################################################################################################
# preparation steps

# These steps define the classes to load in the preparation step and which parameters to set
# The classes are loaded and executed in the order of loading
preparation:
  - # class name
    class: Dummy
    # module name - should be in PYTHONPATH
    module: modules.preparation
    # variables to pass to the object (not in constructor, but set directly). Constructor must not have required parameters.
    args:
      test: Test Argument passed from config.
    # Execution conditions, see below
    conditions: {}
# You can chain modules by adding them to the preparation array. Here is an example using settings from the connection
# settings defined above:

# GraphLoad will try to load a saved graph file from disk or from database. By convention, we take the .pkl extension
# for Python Pickle files (because this is what the file contains). By default, the module will try to load a pickled
# file. If it does not find one, it will get the data from the database. After this, it will save the graph to a
# pickled file, so we do not have to get data from db on the next run.
  - class: GraphLoad
    module: modules.preparation
    args:
      # connection definition set above
      connection: psql_default
      # filename of pickled graph
      filename: 'saved_graph.pkl'
      # save to pickled graph if retrieved from db
      save: true

# DebugDisplayPathsAndHubs is a utility module to check if everything went smoothly during preparation. The options are:
# "draw_network": Draw or save a network graph. Dependent options are: "save_network": Save graph as file to disk.
# "show_network": Display network on stdout (depends on platform). If save_network is true, "save_network_name" and
# "save_network_type" will define the output file name and type. Possible file types are eps, jpeg, jpg, pdf, pgf, png,
# ps, raw, rgba, svg, svgz, tif, tiff.
# "display_routes": Display an example route. You need to define "start" and "end" hub ids. "show_graphs" will plot
# graphs to stdout (depends on platform). "save_graphs" defines, if graphs should be saved (multiple files are
# possible). Like above, "save_graphs_names" and "save_graphs_type" define file names and types (same possible values).
  - class: DebugDisplayPathsAndHubs
    module: modules.preparation
    args:
      draw_network: true
      show_network: false
      save_network: true
      save_network_name: network
      save_network_type: png
      display_routes: false
      start: *simulation_start
      end: *simulation_end
      show_graphs: false
      save_graphs: true
      save_graphs_names: possible_routes
      save_graphs_type: png

# Create actual routes for simulation - this is important in order for the simulation to run. It takes two parameters:
# maximum_routes: if greater than 0, this is the maximum number of routes to retain (sorted by shortest routes)
# maximum_difference_from_shortest: if greater than 1, this is the maximum difference of a route from the shortest one
# (in factor) to be retained in the list.
  - class: CreateRoutes
    module: modules.preparation
    args:
      maximum_routes: 0
      maximum_difference_from_shortest: 2.0


# The ConditionalModule is a utility module to bundle multiple modules with one condition check (so you do not have to
# repeat the conditions for every single step. In our example the check is not_data_must_exist. This will check if the
# data does *not* exist (conditions can be negated by prefixing them with "not_"). Here the class instance "context"
# will be tested for the instance variable "graph". What does this mean? Consider the first entry, GraphLoad. The
# module will load a saved graph, if a save file exists. If it exists, context.graph will have been populated by the
# time ConditionalModule is executed. Consequently, all the submodules will be skipped, if the graph was loaded. If not,
# the ConditionalModule will be run (context.graph will be empty).


########################################################################################################################
# simulation - is a bit more complicated, because there are several hooks to add modules to

# steps that are run at the start of each day
simulation_prepare_day: []
# steps that are run at each step to define the state
simulation_define_state: []
# steps run during simulation phase - these will update the state and calculate time taken, etc.
# Often, you will only need one simulation module to work out all the time and stop factors.
simulation_step:
  - class: Simple
    module: modules.simulation_step
    args:
      # kph of this agent
      speed: 5.0
      # time taken is modified by slope in percents multiplied by this number when ascending
      ascend_slowdown_factor: 0.05
      # time taken is modified by slope in percents multiplied by this number when descending
      descend_slowdown_factor: 0.025
      # conditions define conditions that must be true in order to execute this step
      conditions:
        # check type of next leg to be a road
        types: ['road']
  - class: DummyFixedSpeed
    module: modules.simulation_step
    args:
      # kph of agent in this stepper
      speed: 4.0
      conditions:
        # type must not be a road
        not_types: ['road']

########################################################################################################################
# output steps

# These steps define the classes to load in the output step and which parameters to set
# The classes are loaded and executed in the order of loading
output:
  - class: JSONOutput
    module: modules.output
    args:
      # convert to string
      to_string: true
      # show output in log
      show_output: false
      # save output to file?
      save_output: false
      # output filename
      filename: simulation_output.json
      # indent output to display json in a nice way (if > 0, indent by this number of spaces)?
      indent: 0