Inputs

Scenario Config

Scenarios are run by reading a YAML file describing the parameters of the simulation. The files list all scenario-specific parameters but can fall back to defaults set here.

Scenario YAML files organize a list of resource files to use as input. If a file resource is listed which doesn’t resolve to a local file path, HIVE will search for a default resource here. By default, HIVE expects file resources stored in a directory matching their resource type.

Note

some inputs in hive are optional and will fall back to defaults if not specified; here we will denote whether the input is (required) or (optional); take a look at nrel.hive.resources.defaults.hive_config.yaml for the optional fallbacks

sim:
  # (required) any name you want to give your simulation (go ahead, be creative);
  sim_name: denver_demo

  # (required) the start time of the simulation;
  start_time: "1970-01-01T00:00:00"

  # (required) the end time of the simulation;
  end_time: "1970-01-02T00:00:00"

  # (optional) how many seconds does a single hive time step represent;
  # must be an integer; generally, 60 seconds is the recommended value based on internal testing and validation;
  timestep_duration_seconds: 60

  # (optional) represents how long a request will be active in the simulation;
  # after this timeout the request is destroyed;
  request_cancel_time_seconds: 600

  # (optional) what is the atomic unit of the simulation;
  # 15 is equivalent to approximately 1 meter;
  sim_h3_resolution: 15

  # (optional) which h3 resolution should we search for entities?
  sim_h3_search_resolution: 7

  # (optional) if using human drivers, what type of schedule should we use?
  schedule_type: "time_range"

network:
  # (required) what type of network to use; options: osm_network | euclidean
  network_type: osm_network

  # (optional) if no speed exists in the road network data input, we fill it in with this value;
  default_speed_kmph: 40.0

input:
  # (required)
  vehicles_file: denver_demo_vehicles.csv

  # (required)
  requests_file: denver_demo_requests.csv

  # (required)
  bases_file: denver_demo_bases.csv

  # (required)
  stations_file: denver_demo_stations.csv

  # (optional) only used with `network_type: osm_network`
  road_network_file: downtown_denver_network.json

  # (optional) defaults to zero cost if not specified
  rate_structure_file: rate_structure.csv

  # (optional) defaults to zero cost if not specified
  charging_price_file: denver_charging_prices_by_geoid.csv

dispatcher:


  # (optional) how often should we issue dispatching instructions?  
  default_update_interval_seconds: 600


  # (optional) ingnore searching for any entity beyond this threshold  
  max_search_radius_km: 100.0

  ## Parameters for the default matching dispatcher

  # (optional) don't match requests to vehicles beyond this range 
  matching_range_km_threshold: 20 

  # (optional) which states will the default matching dispatcher consider valid?
  valid_dispatch_states:
    - Idle
    - Repositioning

  ## Parameters for the default charging dispatcher

  # (optional) how to search for stations? nearest_shortest_queue | shortest_time_to_charge 
  charging_search_type: nearest_shortest_queue 

  # (optional) ignore charging at stations when remaining range is greater than this plus the nearest station distance
  charging_range_km_threshold: 20               

  # (optional) ignore charging at stations when remaining range is greater than this 
  charging_range_km_soft_threshold: 50          

  # (optional) ignore base charging at bases more than this threshold 
  base_charging_range_km_threshold: 100         


  ## Parameters for the driver control

  # (optional) SOC target for fast charging at a station 
  ideal_fastcharge_soc_limit: 0.8

  # (optional) how long do drivers idle before returning to a base?  
  idle_time_out_seconds: 1800

Scenario Files

In addition to the scenario config yaml file, each scenario has several other files used to describe the scenario.

Bases

Bases are specified as one base per csv line with the following fields:

base_id: the unique id for this base
lon: the longitude for the base location
lat: the latitude for the base location
stall_count: how many vehicles can this base accomodate
station_id: (optional) the id of a station co-located with the base

Chargers

Chargers are specified as one charger per csv line with the following fields:

charger_id: the unique identifier of the charger type
energy_type: the type of energy (electric | gasoline)
rate: the rate of discharge
units: the units for the rate of discharge

Charging Prices

Charging prices are specified in a csv file and can be specified two different ways:

Price per station with the following fields:
- time: the time when the price becomes valid (allows for varible price schemes)
- station_id: which station this pricing applies to
- charger_id: which charger this pricing applies to
- price_kwh: the cost (in dollars) per kilowatthour of energy
Price per region
- time: the time when the price becomes valid (allows for varible price schemes)
- geoid: the geoid of the region this pricing scheme applies to
- charger_id: which charger this pricing applies to
- price_kwh: the cost (in dollars) per kilowatthour of energy

Fleets

Fleets are specified with a yaml file.

Each key represents the identifies of a fleet and then each sub key represents which entities are part of that fleet.

For example, let’s say we have this fleet file:

tnc_1:
  vehicles:
    - v1   
    - v2   
  stations:
    - s1
  bases:
    - b1

tnc_2:
  vehicles:
    - v1   
    - v3   
  stations:
    - s2
  bases:
    - b2

In this case, vehicle v1 belongs to both fleets and so would have access to all entities listed here. Vehicle v2 is only in the fleet tnc_1 and so would only have access to the stations s1.

Note

if an entity is not specified in this file or if this file is not specified in the scenario config, the simulation will tag it with a ‘public’ membership and there will be no restrictions entity interactions.

Mechatronics

Mechatronics refers to the vehicle level parameters and is specified with a yaml file.

Each key in this file refers to a mechatronics id and each sub key is a specific parameter of that mechatronics type.

For example, let’s say we have this mechatronics file:

leaf_50:
  mechatronics_type: bev
  powercurve_file: 'normalized.yaml'
  powertrain_file: 'normalized-electric.yaml'
  battery_capacity_kwh: 50
  nominal_max_charge_kw: 50
  charge_taper_cutoff_kw: 10
  nominal_watt_hour_per_mile: 225
  idle_kwh_per_hour: 0.8
  
toyota_corolla:
  mechatronics_type: ice
  tank_capacity_gallons: 10
  idle_gallons_per_hour: 0.2
  powertrain_file: 'normalized-gasoline.yaml'
  nominal_miles_per_gallon: 30

There are currently two supported mechatronics types: bev (battery electric vehicle) and ice (internal combustion engine). In this case, the leaf_50 is a bev and requires the following sub keys:

mechatronics_type: the mechatronics type for this vehicle is bev
powercurve_file: the powercurve file that contains the power curve for this vehicle
powertrain_file: the powertrain file that contains the energy consumption model for this vehicle
battery_capacity_kwh: the battery capacity in kilowatt-hours
nominal_max_charge_kw: the nominal max charge in kilowatts
charge_taper_cutoff_kw: the charge taper cuttoff in kilowatts
nominal_watt_hour_per_mile: the nominal watt-hours per mile
idle_kwh_per_hour: the amount of kilowatt-hours used per hour while idling

The toyota_corolla in this case is an ice and requires the following sub keys:

mechatronics_type: the mechatronics type for this vehicle is ice
tank_capacity_gallons: the vehicle’s tank capacity in gallons
idle_gallons_per_hour: the amount of gallons used per hour while the vehicle is idling
powertrain_file: the powertrain file that contains the energy consumption model for this vehicle
nominal_miles_per_gallon: the nominal miles per gallon

A scenario can have multiple mechatronics types and each vehicle in the simulation can be assigned a mechatronics type in the vehicles file.

Requests

Requests are specified as one request per csv line with the following fields:

request_id: the unique request identifier
o_lat: the latitude of the request origin
o_lon: the longitude of the request origin
d_lat: the latitude of the request destination
d_lon: the longitude of the request destination
departure_time: when this request comes into the system
passengers: the number of passengers associated with this request

Road Network

The road network file is a json file that is built using the osmnx package.

You can find an example of building a road network here

Note

If this file is not specified, the model uses a euclidean style graph where vehicles travel in straight lines between the origin and destination

Service Prices

Service prices are optional (the default is zero price for all requests).

Service prices are specified in a csv file and if specified, the following fields are required:

base_price: the base price of a request (dollars)
price_per_mile: an additional price per mile (dollars)
minimum_price: the minimum request price (dollars)

Stations

Stations are specified as one station per csv line in the file with the following fields:

station_id: a unique identifier for the station
lat: the latitude of the station location
lon: the longitude of the station location
charger_count: how many chargers of type charger_id are at this station
charger_id: the corresponding charger id
on_shift_access: is this station available to on shift human drivers?

Stations

Stations are specified as one station per csv line in the file with the following fields:

station_id: a unique identifier for the station
lat: the latitude of the station location
lon: the longitude of the station location
charger_count: how many chargers of type charger_id are at this station
charger_id: the corresponding charger id
on_shift_access: is this station available to on shift human drivers?

Vehicles

Vehicles are specified as one vehicle per csv line with the following fields:

vehicle_id: a unique id for the vehicle
lat: the latitude of the vehicle starting location
lon: the longitude of the vehicle starting location
mechatronics_id: the identifier of the mechatronics that this vehicle is using
initial_soc: the initial state of charge for the vehicle
schedule_id: (optional) the schedule this vehicle should follow (human driver)
home_base_id: (optional) the base id for the home base location (human driver)

Global Config

All of the inputs described above are scenario specific. Hive also has global configuration values that will apply to all scenarios. By default, if no config file is found the simulation will use the defaults specified at nrel.hive.resources.default..hive.yaml:

# where should we write outputs from a scenario?
output_base_directory: ""

# whether or not to log the console output from a run 
log_run: True

# whether or not to log the states for all entities at all timesteps; 
# this file can get very large for big scenarios but contains detailed information; 
log_states: True

# whether or not to log events when they occur (i.e. a charging event) 
log_events: True

# whether or not to log kepler.gl inputs
log_kepler: False

# whether or not to log issued instructions 
log_instructions: True

# whether or not to log aggregate statistics like total vehicle miles traveled 
log_stats: True

# python logging level 
log_level: INFO

# which states and events to log 
log_sim_config:
- 'instruction'
- 'station_state'
- 'vehicle_state'
- 'driver_state'
- 'add_request_event'
- 'cancel_request_event'
- 'pickup_request_event'
- 'dropoff_request_event'
- 'vehicle_charge_event'
- 'vehicle_move_event'
- 'station_load_event'
- 'refuel_search_event'
- 'driver_schedule_event'

# whether or not to log station capacities 
log_station_capacities: True

# whether or not to log time step level statistics 
log_time_step_stats: True

# whether or not to log fleet time step level statistics 
log_fleet_time_step_stats: True

# level of parallelism for a single scenario (NOTE: this is not yet used) 
local_parallelism: 1

# parallelism timeout (NOTE: this is not yet used) 
local_parallelism_timeout_sec: 60

# whether or not to read files lazily;
# this is useful is you have very large inputs and don't want to read all into memory at the start 
lazy_file_reading: False

# If True, well know text inputs are read (X, Y) 
wkt_x_y_ordering: True

# If True, we print out more detail information in the logs 
verbose: True

To override any of the default global config values, you can create your own .hive.yaml file.

When a hive scenario is loaded, hive will search for a .hive.yaml file to load. First, hive looks in the same location that you called hive <scenario_file.yaml>. Then, if it can’t find it there it will step up to the parent and keep stepping up all the way to the root of the file system. If there are no files in any of these locations, it will look in the users home directory (i.e. ~/). Finally, if no .hive.yaml files exist in any of these locations, the defaults are loaded.

As an example, we can write a new .hive.yaml file into our home directory (touch ~/.hive.yaml) that looks like this:

output_base_directory: "~/hive_results"

Now, whenever we run a hive simulation, our results will get written to ~/hive_results.

But, what if we want to run a scenario and only log certain things? We can create a new .hive.yaml file in the scenario directory (touch <path/to/scenario-dir/.hive.yaml) that looks like:

log_run: False 
log_states: False 
log_events: True 
log_stats: False 
log_station_capacities: False 
log_level: INFO
log_sim_config:
- 'vehicle_charge_event'

This would turn off all logging except for vehicle charge events.