ECLIPSE(1)

📦

version 1.27.1 · 7 versions

💖 ECLIPSE(1) — the group chat version 💖

okay bestie, buckle up, this is the manual page for ECLIPSE, and it is long. we're doing this in parts. iykyk. 🦋

✨ NAME ✨

Eclipse — a microscopic, multi-modal traffic simulation. yes, microscopic. yes, multi-modal. she contains multitudes, periodt. 💅

🚗 SYNOPSIS 🚗

sumo [OPTION]*

literally just run it with whichever options you want, no cap.

🌈 DESCRIPTION 🌈

Eclipse SUMO — sumo 1.27.1

A microscopic, multi-modal traffic simulation. that's the whole vibe. 🚦🚗🚲🚶

⚙️ Configuration Options ⚙️

like, the settings settings. how you tell her where to read from and where to dump stuff. 🌸

-c, --configuration-file FILE — loads the named config on startup. your lil startup recipe.
-C, --save-configuration FILE — saves the current configuration into FILE. so she remembers what you two did. 🫶
--save-configuration.relative — enforce relative paths when saving the configuration. keeps things cute and portable.
--save-template FILE — saves a configuration template (empty) into FILE. a blank lil canvas, iconic.
--save-schema FILE — saves the configuration schema into FILE.
--save-commented — adds comments to the saved template, configuration, or schema. so future you isn't confused, bestie.

📥 Input Options 📥

where all the data comes in. the reading era.

-n, --net-file FILE — load the road network description from FILE. this is the actual map, the bones of it all. 🗺️
-r, --route-files FILE — load route descriptions from FILE(s). plural, she can take many.
-a, --additional-files FILE — load further descriptions from FILE(s). the extras.
-w, --weight-files FILE — load edge/lane weights for online rerouting from FILE.
-x, --weight-attribute STR — name of the xml attribute which gives the edge weight.
--load-state FILE — loads a network state from FILE. mid-scene entry, main character energy.
--load-state.offset TIME — shifts all times loaded from a saved state by the given offset.
--load-state.remove-vehicles STR[] — removes vehicles with the given IDs from the loaded state. bye babes. 👋
--junction-taz — initialize a TAZ for every junction, to use the attributes toJunction and fromJunction.

📤 Output Options 📤

okay this is the big one. everything she can spit out at you. hydrate. 💧

--write-license — include license info into every output file. receipts, legally.
--write-metadata — write parsable metadata (configuration etc.) instead of comments.
--output-prefix STR — prefix applied to all output files. the special string 'TIME' gets replaced by the current time. ✨
--output-suffix STR — suffix applied to all output files. also swaps 'TIME' for the current time.
--precision INT — how many digits after the comma for floating point output.
--precision.geo INT — how many digits after the comma for lon,lat output.
--output.compression STR — defines the standard compression algorithm (currently only for parquet output).
--output.format STR — defines the standard output format if it can't be derived from the file name ('xml', 'csv', 'parquet').
--output.column-header STR — how to derive column headers from attribute names ('none', 'tag', 'auto', 'plain').
--output.column-separator STR — the separator used in CSV output.
-H, --human-readable-time — write time values as hour:minute:second or day:hour:minute:second rather than seconds. she's being nice to your eyeballs.
--netstate-dump FILE — save complete network states into FILE.
--netstate-dump.empty-edges — write also empty edges completely when dumping. don't skip the quiet ones.
--netstate-dump.precision INT — write positions and speeds with the given precision (default 2).
--emission-output FILE — save the emission values of each vehicle.
--emission-output.precision INT — write emission values with the given precision (default 2).
--emission-output.geo — save the positions in emission output using geo-coordinates (lon/lat).
--emission-output.step-scaled — write emission values scaled to the step length rather than as per-second values.
--emission-output.attributes STR[] — list attributes that should be included in the emission output.
--battery-output FILE — save the battery values of each vehicle. 🔋
--battery-output.precision INT — write battery values with the given precision (default 2).
--elechybrid-output FILE — save the elecHybrid values of each vehicle.
--elechybrid-output.precision INT — write elecHybrid values with the given precision (default 2).
--elechybrid-output.aggregated — write elecHybrid values into one aggregated file.
--chargingstations-output FILE — write data of charging stations.
--chargingstations-output.aggregated — write aggregated charging event data instead of single time steps.
--chargingstations-output.aggregated.write-unfinished — write aggregated charging event data for vehicles which have not arrived at simulation end.
--overheadwiresegments-output FILE — write data of overhead wire segments.
--substations-output FILE — write data of electrical substation stations.
--substations-output.precision INT — write substation values with the given precision (default 2).
--fcd-output FILE — save the Floating Car Data.
--fcd-output.geo — save the Floating Car Data using geo-coordinates (lon/lat).
--fcd-output.utm — save the Floating Car Data using utm/unshifted coordinates (x/y).
--fcd-output.signals — add the vehicle signal state to the FCD output (brake lights etc.).
--fcd-output.distance — add kilometrage to the FCD output (linear referencing).
--fcd-output.acceleration — add acceleration to the FCD output.
--fcd-output.speed-relative — add relative speed (vehicle speed / edge speed limit) to the FCD output.
--fcd-output.max-leader-distance FLOAT — add leader vehicle information to the FCD output (within the given distance).
--fcd-output.params STR[] — add generic parameter values to the FCD output.
--fcd-output.filter-edges.input-file FILE — restrict fcd output to the edge selection from the given input file.
--fcd-output.attributes STR[] — list attributes that should be included in the FCD output.
--fcd-output.filter-shapes STR[] — list shape names that should be used to filter the FCD output.
--fcd-output.skip-empty — do not save data for time steps which have no vehicles / transportables. silence, we love her.
--person-fcd-output FILE — save fcd for persons and container to a separate FILE.
--device.ssm.filter-edges.input-file FILE — restrict SSM device output to the edge selection from the given input file.
--full-output FILE — save a lot of information for each timestep (very redundant). she's an over-sharer, we stan. 😭
--queue-output FILE — save the vehicle queues at the junctions (experimental).
--queue-output.period TIME — save vehicle queues with the given period.
--vtk-output FILE — save complete vehicle positions inclusive speed values in the VTK format (usage: /path/out will produce /path/out_$TIMESTEP$.vtp files).
--amitran-output FILE — save the vehicle trajectories in the Amitran format.
--summary-output FILE — save aggregated vehicle departure info into FILE.
--summary-output.period TIME — save summary-output with the given period.
--person-summary-output FILE — save aggregated person counts into FILE.
--tripinfo-output FILE — save single vehicle trip info into FILE.
--tripinfo-output.write-unfinished — write tripinfo output for vehicles which have not arrived at simulation end.
--tripinfo-output.write-undeparted — write tripinfo output for vehicles which have not departed at simulation end because of depart delay.
--personinfo-output FILE — save personinfo and containerinfo to a separate FILE.
--vehroute-output FILE — save single vehicle route info into FILE.
--vehroute-output.exit-times — write the exit times for all edges.
--vehroute-output.last-route — write the last route only.
--vehroute-output.sorted — sorts the output by departure time.
--vehroute-output.dua — write the output in the duarouter alternatives style.
--vehroute-output.cost — write costs for all routes.
--vehroute-output.intended-depart — write the output with the intended instead of the real departure time.
--vehroute-output.route-length — include total route length in the output.
--vehroute-output.write-unfinished — write vehroute output for vehicles which have not arrived at simulation end.
--vehroute-output.skip-ptlines — skip vehroute output for public transport vehicles.
--vehroute-output.incomplete — include invalid routes and route stubs in vehroute output.
--vehroute-output.stop-edges — include information about edges between stops.
--vehroute-output.speedfactor — write the vehicle speedFactor (defaults to 'true' if departSpeed is written).
--vehroute-output.internal — include internal edges in the output.
--personroute-output FILE — save person and container routes to a separate FILE.
--link-output FILE — save link states into FILE.
--railsignal-block-output FILE — save railsignal-blocks into FILE.
--railsignal-vehicle-output FILE — record entry and exit times of vehicles for railsignal blocks into FILE.
--bt-output FILE — save bluetooth visibilities into FILE (in conjunction with device.btreceiver and device.btsender).
--lanechange-output FILE — record lane changes and their motivations for all vehicles into FILE.
--lanechange-output.started — record start of lane change manoeuvres.
--lanechange-output.ended — record end of lane change manoeuvres.
--lanechange-output.xy — record coordinates of lane change manoeuvres.
--stop-output FILE — record stops and loading/unloading of passenger and containers for all vehicles into FILE.
--stop-output.write-unfinished — write stop output for stops which have not ended at simulation end.
--collision-output FILE — write collision information into FILE. 💀
--edgedata-output FILE — write aggregated traffic statistics for all edges into FILE.
--lanedata-output FILE — write aggregated traffic statistics for all lanes into FILE.
--statistic-output FILE — write overall statistics into FILE.
--deadlock-output FILE — write reports on deadlocks into FILE.
--save-state.times STR[] — use TIME[] as the times at which a network state gets written.
--save-state.period TIME — save state repeatedly after the TIME period.
--save-state.period.keep INT — keep only the last INT periodic state files.
--save-state.prefix FILE — prefix for network states.

okay bestie that's the config + input + output stack, and there's more coming, so don't go anywhere. 🎀

--save-state.suffix STR — okay so this sets the suffix for network states, bestie, and the vibe is either .xml.gz or .xml. ✨
--save-state.files FILE — tells it which FILEs to use for network states. 💖
--save-state.rng — saves random number generator states. The RNG gets its own little snapshot, periodt. 🎲
--save-state.transportables — saves person and container states. Heads up: this one is experimental, so it's giving handle-with-care energy, fr fr. 🫶
--save-state.constraints — saves rail signal constraints. 🚦
--save-state.precision INT — writes internal state values with the given precision (default is 2). 🔍

⏰ Time Options ⏰

-b, --begin TIME — defines the begin time in seconds; the simulation starts at this time. ⏰
-e, --end TIME — defines the end time in seconds; the simulation ends at this time. 🛑
--step-length TIME — defines the step duration in seconds. 👟

🛠️ Processing Options 🛠️

--step-method.ballistic — whether to use ballistic method for the positional update of vehicles (default is a semi-implicit Euler method). Physics bestie moment. 🚗
--extrapolate-departpos — whether vehicles that depart between simulation steps should extrapolate the depart position. 📍
--threads INT — defines the number of threads for parallel simulation. Parallel besties, assemble. 👯
--lateral-resolution FLOAT — defines the resolution in m when handling lateral positioning within a lane (with -1 all vehicles drive at the center of their lane. 🛣️
-s, --route-steps TIME — load routes for the next number of seconds ahead. 🗺️
--no-internal-links — disable (junction) internal links. 🚧
--ignore-junction-blocker TIME — ignore vehicles which block the junction after they have been standing for SECONDS (-1 means never ignore). 🚫
--ignore-route-errors — do not check whether routes are connected. 🙈
--ignore-accidents — do not check whether accidents occur. 💥
--collision.action STR — how to deal with collisions: [none,warn,teleport,remove]. 💀
--intermodal-collision.action STR — how to deal with collisions between vehicle and pedestrian: [none,warn,teleport,remove]. 🚶
--collision.stoptime TIME — let vehicle stop for TIME before performing collision.action (except for action 'none'). ⏸️
--intermodal-collision.stoptime TIME — let vehicle stop for TIME before performing intermodal-collision.action (except for action 'none'). 🛑
--collision.check-junctions — enables collisions checks on junctions. 🚦
--collision.check-junctions.mingap FLOAT — increase or decrease sensitivity for junction collision check. 📏
--collision.mingap-factor FLOAT — sets the fraction of minGap that must be maintained to avoid collision detection. If a negative value is given, the carFollowModel parameter is used. 🔍
--keep-after-arrival TIME — after a vehicle arrives, keep it in memory for the given TIME (for TraCI access). 🧠
--max-num-vehicles INT — delay vehicle insertion to stay within the given maximum number. 🚗
--max-num-persons INT — delay person insertion to stay within the given maximum number. 🚶
--max-num-teleports INT — abort the simulation if the given maximum number of teleports is exceeded. 🛑
--scale FLOAT — scale demand by the given factor (by discarding or duplicating vehicles). ⚖️
--scale-suffix STR — suffix to be added when creating ids for cloned vehicles. 🏷️
--time-to-teleport TIME — specify how long a vehicle may wait until being teleported, defaults to 300, non-positive values disable teleporting. ⏳
--time-to-teleport.highways TIME — the waiting time after which vehicles on a fast road (speed > 69km/h) are teleported if they are on a non-continuing lane. 🛣️
--time-to-teleport.highways.min-speed FLOAT — the waiting time after which vehicles on a fast road (default: speed > 69km/h) are teleported if they are on a non-continuing lane. 🚗
--time-to-teleport.disconnected TIME — the waiting time after which vehicles with a disconnected route are teleported. Negative values disable teleporting. 🧭
--time-to-teleport.remove — whether vehicles shall be removed after waiting too long instead of being teleported. 🗑️
--time-to-teleport.remove-constraint — whether rail-signal-constraint based deadlocks shall be cleared by removing a constraint. 🚦
--time-to-teleport.ride TIME — the waiting time after which persons / containers waiting for a pickup are teleported. Negative values disable teleporting. 🛺
--time-to-teleport.bidi TIME — the waiting time after which vehicles on bidirectional edges are teleported. 🔁
--time-to-teleport.railsignal-deadlock TIME — the waiting time after which vehicles in a rail-signal based deadlock are teleported. 🚆
--waiting-time-memory TIME — length of time interval, over which accumulated waiting time is taken into account (default is 100s.). ⏱️
--startup-wait-threshold TIME — minimum consecutive waiting time before applying startupDelay. 🕒
--max-depart-delay TIME — how long vehicles wait for departure before being skipped, defaults to -1 which means vehicles are never skipped. 🚦
--sloppy-insert — whether insertion on an edge shall not be repeated in same step once failed. 🫠
--eager-insert — whether each vehicle is checked separately for insertion on an edge. 🏎️
--emergency-insert — allow inserting a vehicle in a situation which requires emergency braking. 🚨
--insertion-checks STR — override default value for vehicle attribute insertionChecks. 🔧
--random-depart-offset TIME — each vehicle receives a random offset to its depart value drawn uniformly from [0, TIME]. 🎲
--lanechange.duration TIME — duration of a lane change maneuver (default 0). 🔄
--lanechange.overtake-right — whether overtaking on the right on motorways is permitted. 🏁
--tls.all-off — switches off all traffic lights. 🚦
--tls.actuated.show-detectors — sets default visibility for actuation detectors. 👀
--tls.actuated.jam-threshold FLOAT — sets default jam-threshold parameter for all actuation detectors. 🚗
--tls.actuated.detector-length FLOAT — sets default detector length parameter for all actuation detectors. 📏
--tls.delay_based.detector-range FLOAT — sets default range for detecting delayed vehicles. 📡
--tls.yellow.min-decel FLOAT — minimum deceleration when braking at yellow. 🟡
--railsignal-moving-block — let railsignals operate in moving-block mode by default. 🚆
--railsignal.moving-block.default-classes STR[] — list vehicle classes that default to moving-block operations. 🚃
--railsignal.moving-block.max-dist FLOAT — maximum signal distance above which zipper conflicts are ignored. 📐
--railsignal.max-block-length FLOAT — do not build blocks longer than FLOAT and issue a warning instead. ⚠️
--railsignal.default-classes STR[] — list vehicle classes that uses block-based insertion checks even when the network has no rail signals for them. 🚦
--time-to-impatience TIME — specify how long a vehicle may wait until impatience grows from 0 to 1, defaults to 300, non-positive values disable impatience growth. 😤
--default.departspeed STR — select default depart speed. 🚗
--default.departlane STR — select default depart lane. 🛣️
--default.action-step-length FLOAT — length of the default interval length between action points for the car-following and lane-change models (in seconds). If not specified, the simulation step-length is used per default. Vehicle- or VType-specific settings override the default. Must be a multiple of the simulation step-length. ⏱️
--default.carfollowmodel STR — select default car following model (Krauss, IDM, ...). 🚗
--default.speeddev FLOAT — select default speed deviation. A negative value implies vClass specific defaults (0.1 for the default passenger class). 🎚️
--default.emergencydecel STR — select default emergencyDecel value among ('decel', 'default', FLOAT) which sets the value either to the same as the deceleration value, a vClass-class specific default or the given FLOAT in m/s^2. 🛑
--overhead-wire.solver — use Kirchhoff's laws for solving overhead wire circuit. ⚡
--overhead-wire.recuperation — enable recuperation from the vehicle equipped with elecHybrid device into the overhead wire. 🔋
--overhead-wire.substation-current-limits — enable current limits of traction substation during solving the overhead wire electrical circuit. ⚡
--emergencydecel.warning-threshold FLOAT — sets the fraction of emergency decel capability that must be used to trigger a warning. ⚠️
--parking.maneuver — whether parking simulation includes maneuvering time and associated lane blocking. 🅿️
--use-stop-ended — override stop until times with stop ended times when given. ⏹️
--use-stop-started — override stop arrival times with stop started times when given. ▶️
--pedestrian.model STR — select among pedestrian models ['nonInteracting', 'striping', 'jupedsim', 'remote']. 🚶
--pedestrian.timegap-crossing FLOAT — minimal acceptable gap (in seconds) between two vehicles before starting to cross. 🚸
--pedestrian.striping.stripe-width FLOAT — width of parallel stripes for segmenting a sidewalk (meters) for use with model 'striping'. 🦓
--pedestrian.striping.dawdling FLOAT — factor for random slow-downs [0,1] for use with model 'striping'. 🐢
--pedestrian.striping.mingap-to-vehicle FLOAT — minimal gap / safety buffer (in meters) from a pedestrian to another vehicle for use with model 'striping'. 📏
--pedestrian.striping.jamtime TIME — time in seconds after which pedestrians start squeezing through a jam when using model 'striping' (non-positive values disable squeezing). 🧍
--pedestrian.striping.jamtime.crossing TIME — time in seconds after which pedestrians start squeezing through a jam while on a pedestrian crossing when using model 'striping' (non-positive values disable squeezing). 🚸
--pedestrian.striping.jamtime.narrow TIME — time in seconds after which pedestrians start squeezing through a jam while on a narrow lane when using model 'striping'. 🧍
--pedestrian.striping.jamfactor FLOAT — factor for reducing speed of pedestrian in jammed state. 🐌
--pedestrian.striping.reserve-oncoming FLOAT — fraction of stripes to reserve for oncoming pedestrians. ↔️
--pedestrian.striping.reserve-oncoming.junctions FLOAT — what fraction of the stripes we're setting aside for the pedestrians coming the other way, on crossings and walkingareas. sharing is caring bestie 💖
--pedestrian.striping.reserve-oncoming.max FLOAT — the maximum width, in m, that you'll reserve for those oncoming pedestrians.
--pedestrian.striping.legacy-departposlat — read departPosLat for walks the old-school legacy way, no cap.
--pedestrian.striping.walkingarea-detail INT — generate INT intermediate points so the lanes inside the walkingarea get smoothed out. it's giving ✨polished✨.
--ride.stop-tolerance FLOAT — the tolerance you apply when matching pedestrian and vehicle positions for boarding at individual stops. gotta line up perfectly 🎀
--mapmatch.distance FLOAT — the farthest distance allowed when you're mapping input coordinates (like fromXY etc.) onto the road network. miss by more than this and it's a no 💀
--mapmatch.junctions — match positions to junctions instead of edges, periodt.
--mapmatch.taz — match positions to taz instead of edges. girlboss behaviour 🫶
--weights.turnaround-penalty FLOAT — slap this time penalty on whenever routing costs get computed for turnaround internal lanes.
--weights.reversal-penalty FLOAT — same energy but for the routing costs of train reversal. heads up: negative values disable reversal entirely, so be careful what you wish for 😭
--persontrip.walk-opposite-factor FLOAT — use FLOAT as a factor on walking speed whenever someone's walking against the direction of vehicle traffic.

✨ Routing Options ✨

okay this is the part where the routes get chosen and honestly it's the main character of the whole simulation 💅

--routing-algorithm STR — pick your fighter from 'dijkstra', 'astar', 'CH', 'CHWrapper'.
--weights.random-factor FLOAT — edge weights for routing get randomly disturbed, with the factor drawn uniformly from [1,FLOAT). yes it's chaotic, that's the point 🌈
--weights.random-factor.dynamic — when you're using --weights.random-factor, let that randomness vary over time.
--weights.minor-penalty FLOAT — apply this time penalty when computing the minimum routing costs for minor-link internal lanes.
--weights.tls-penalty FLOAT — scaled travel time penalties based on the green split, applied when computing minimum routing costs for internal lanes at traffic lights. traffic lights get their own lil weighting, iconic 🚦
--weights.priority-factor FLOAT — consider edge priorities on top of travel times, weighted by this factor.
--weights.separate-turns FLOAT — distinguish travel time by turn direction, and shift a fraction of the estimated time loss ahead of the intersection onto the internal edges. it's giving nuance ✨
--astar.all-distances FILE — initialize the astar lookup table from this given file (generated by marouter --all-pairs-output).
--astar.landmark-distances FILE — initialize the astar ALT-variant lookup table from this given file.
--persontrip.walkfactor FLOAT — use FLOAT as a factor on pedestrian maximum speed during intermodal routing.
--persontrip.transfer.car-walk STR[] — where are mode changes from car to walking even allowed? possible values: 'parkingAreas', 'ptStops', 'allJunctions' and combinations of them.
--persontrip.transfer.taxi-walk STR[] — where taxis can drop off customers ('allJunctions', 'ptStops', 'parkingAreas').
--persontrip.transfer.walk-taxi STR[] — where taxis can pick up customers ('allJunctions', 'ptStops', 'parkingAreas').
--persontrip.default.group STR — when you set this, trips going between the same origin and destination will share a taxi by default. carpool core 🚕
--persontrip.taxi.waiting-time TIME — the estimated time it takes for a taxi pickup.
--persontrip.ride-public-line — only use the intended public transport line, not any alternative line that happens to stop at the destination. loyalty 💅
--railway.max-train-length FLOAT — use FLOAT as the maximum train length when initializing the railway router.
--replay-rerouting — replay the exact rerouting sequence from vehroute-output. a little reroute rewind, we love to see it 🔁
--device.rerouting.probability FLOAT — the probability that a vehicle has a 'rerouting' device.
--device.rerouting.explicit STR[] — assign a 'rerouting' device to named vehicles.
--device.rerouting.deterministic — the 'rerouting' devices get set deterministic using a fraction of 1000.
--device.rerouting.period TIME — the period with which the vehicle shall be rerouted.
--device.rerouting.pre-period TIME — the rerouting period before depart.
--device.rerouting.adaptation-weight FLOAT — the weight of prior edge weights for the exponential moving average.
--device.rerouting.adaptation-steps INT — the number of steps for the moving average weight of prior edge weights.
--device.rerouting.adaptation-interval TIME — the interval for updating the edge weights.
--device.rerouting.threshold.factor FLOAT — only reroute if the new route is faster than the current route by the given factor.
--device.rerouting.threshold.constant TIME — only reroute if the new route is faster than the current route by the given TIME.
--device.rerouting.with-taz — use zones (districts) as routing start and endpoints.
--device.rerouting.mode STR — set routing flags (8 ignores temporary blockages).
--device.rerouting.init-with-loaded-weights — use the weight files you passed with --weight-files for initializing edge weights.
--device.rerouting.threads INT — the number of parallel execution threads used for rerouting. multitasking queen 👑
--device.rerouting.synchronize — let rerouting happen at the same time for all vehicles.
--device.rerouting.railsignal — allow rerouting triggered by rail signals.
--device.rerouting.bike-speeds — compute separate average speeds for bicycles. bikes deserve their own numbers fr fr 🚲
--device.rerouting.output FILE — save the adapting weights to FILE.
--person-device.rerouting.probability FLOAT — the probability that a person has a 'rerouting' device.
--person-device.rerouting.explicit STR[] — assign a 'rerouting' device to named persons.
--person-device.rerouting.deterministic — the 'rerouting' devices get set deterministic using a fraction of 1000.
--person-device.rerouting.period TIME — the period with which the person shall be rerouted.
--person-device.rerouting.mode STR — set routing flags (8 ignores temporary blockages).
--person-device.rerouting.scope STR — which part of the person plan is to be replaced (stage, sequence, or trip).

📋 Report Options 📋

the "tell me everything" section, and honestly? we're nosy, we want the tea ☕

-v, --verbose — switches to verbose output.
--print-options — prints option values before processing.
-?, --help — prints this screen, or selected topics.
-V, --version — prints the current version.
-X, --xml-validation STR — set the schema validation scheme for XML inputs ("never", "local", "auto" or "always").
--xml-validation.net STR — set the schema validation scheme for SUMO network inputs ("never", "local", "auto" or "always").
--xml-validation.routes STR — set the schema validation scheme for SUMO route inputs ("never", "local", "auto" or "always").
-W, --no-warnings — disables output of warnings. ignorance is bliss I guess 🙈
--aggregate-warnings INT — aggregate warnings of the same type whenever more than INT of them occur.
-l, --log FILE — writes all messages to FILE (and yes, this implies verbose).
--message-log FILE — writes all non-error messages to FILE (implies verbose too).
--error-log FILE — writes all warnings and errors to FILE.
--log.timestamps — writes timestamps in front of all messages.
--log.processid — writes the process ID in front of all messages.
--language STR — language to use in messages.
--duration-log.disable — disable performance reports for individual simulation steps.
-t, --duration-log.statistics — enable statistics on vehicle trips. numbers girlies rise 🙌
--no-step-log — disable console output of the current simulation step.
--step-log.period INT — number of simulation steps between step-log outputs.

🌫️ Emissions Options 🌫️

vroom vroom but make it measurable 🌎

--emissions.volumetric-fuel — return fuel consumption values in the (legacy) unit l instead of mg.
--phemlight-path FILE — determines where to load PHEMlight definitions from.
--phemlight-year INT — enable fleet age modelling with the given reference year in PHEMlight5.
--phemlight-temperature FLOAT — set the ambient temperature to correct NOx emissions in PHEMlight5.
--device.emissions.probability FLOAT — the probability for a vehicle to have an 'emissions' device.
--device.emissions.explicit STR[] — assign an 'emissions' device to named vehicles.
--device.emissions.deterministic — the 'emissions' devices are set deterministic using a fraction of 1000.
--device.emissions.begin STR — recording begin time for emission-data.
--device.emissions.period STR — recording period for emission-output.

📡 Communication Options 📡

bluetooth device girlies, this one's for you 🦋

--device.btreceiver.probability FLOAT — the probability for a vehicle to have a 'btreceiver' device.
--device.btreceiver.explicit STR[] — assign a 'btreceiver' device to named vehicles.
--device.btreceiver.deterministic — the 'btreceiver' devices are set deterministic using a fraction of 1000.
--device.btreceiver.range FLOAT — the range of the bt receiver.
--device.btreceiver.all-recognitions — whether all recognition points shall be written.
--device.btreceiver.offtime FLOAT — the offtime used for calculating detection probability (in seconds).
--device.btsender.probability FLOAT — the probability for a vehicle to have a 'btsender' device.
--device.btsender.explicit STR[] — assign a 'btsender' device to named vehicles.
--device.btsender.deterministic — the 'btsender' devices are set deterministic using a fraction of 1000.
--person-device.btsender.probability FLOAT — the probability for a person to have a 'btsender' device.
--person-device.btsender.explicit STR[] — assign a 'btsender' device to named persons.
--person-device.btsender.deterministic — the 'btsender' devices are set deterministic using a fraction of 1000.
--person-device.btreceiver.probability FLOAT — the probability for a person to have a 'btreceiver' device.
--person-device.btreceiver.explicit STR[] — assign a 'btreceiver' device to named persons.
--person-device.btreceiver.deterministic — the 'btreceiver' devices are set deterministic using a fraction of 1000.

🔋 Battery Options 🔋

--device.stationfinder.probability FLOAT — the probability for a vehicle to have a 'stationfinder' device.
--device.stationfinder.explicit STR[] — hand out a stationfinder device to the vehicles you name, bestie, you pick 'em 💖
--device.stationfinder.deterministic — makes the stationfinder devices deterministic by using a fraction of 1000 ✨
--device.stationfinder.rescueTime TIME — how long to wait for a rescue vehicle at the roadside when the battery's dead 💀
--device.stationfinder.rescueAction STR — what to do with a vehicle that has to stop because the battery's low: [none, remove, tow] 🚗
--device.stationfinder.reserveFactor FLOAT — scale the battery need by this factor so unexpected traffic situations don't catch you off guard 🫶
--device.stationfinder.emptyThreshold FLOAT — the battery percentage at which it goes into rescue mode 😭
--device.stationfinder.radius TIME — search radius, in travel time seconds ⏱️
--device.stationfinder.maxEuclideanDistance FLOAT — Euclidean search distance in meters (yes queen, a negative value disables that restriction entirely) 📏
--device.stationfinder.repeat TIME — when to trigger a brand new search if no station has been found 🎀
--device.stationfinder.maxChargePower FLOAT — the max charging speed of the vehicle battery ⚡
--device.stationfinder.chargeType STR — type of energy transfer 🔌
--device.stationfinder.waitForCharge TIME — after this waiting time, the vehicle goes looking for a new station when the first one is blocked 🙈
--device.stationfinder.minOpportunityDuration TIME — only stops predicted to last at least this threshold long get considered for opportunistic charging 👑
--device.stationfinder.saturatedChargeLevel FLOAT — the target state of charge after which the vehicle stops charging 🌸
--device.stationfinder.needToChargeLevel FLOAT — the state of charge at which the vehicle starts searching for charging stations 🔍
--device.stationfinder.opportunisticChargeLevel FLOAT — the state of charge below which the vehicle may hunt for charging opportunities along its planned stops 🦋
--device.stationfinder.replacePlannedStop FLOAT — the share of stopping time of the next independently planned stop that gets used for charging instead 💅
--device.stationfinder.maxDistanceToReplacedStop FLOAT — max distance in meters from the original stop that can be replaced by the charging stop 📐
--device.stationfinder.chargingStrategy STR — set a charging strategy to alter time and charging load, from the set: [none, balanced, latest] 🧚
--device.stationfinder.checkEnergyForRoute — only search for charging stations if the battery charge isn't estimated as sufficient to complete the current route 🔥
--device.battery.probability FLOAT — the probability that a vehicle has a battery device 🍓
--device.battery.explicit STR[] — assign a battery device to named vehicles ✨
--device.battery.deterministic — the battery devices get set deterministic using a fraction of 1000 💫
--device.battery.track-fuel — track fuel consumption for non-electric vehicles ⛽

🌈 Example Device Options 🌈

--device.example.probability FLOAT — the probability for a vehicle to have a example device 🎀
--device.example.explicit STR[] — assign a example device to named vehicles 💖
--device.example.deterministic — the example devices are set deterministic using a fraction of 1000 ✨
--device.example.parameter FLOAT — an exemplary parameter which can be used by every single instance of the example device 👑

💜 SSM Device Options 💜

--device.ssm.probability FLOAT — the probability for a vehicle to have a ssm device 🦋
--device.ssm.explicit STR[] — assign a ssm device to named vehicles 🌸
--device.ssm.deterministic — the ssm devices are set deterministic using a fraction of 1000 ⭐
--device.ssm.measures STR — says which measures get logged (as a space- or comma-separated sequence of IDs in ('TTC', 'DRAC', 'PET', 'PPET', 'MDRAC')) 📊
--device.ssm.thresholds STR — space- or comma-separated thresholds that correspond to the specified measures (peep the documentation and watch the order!). Only events that exceed the thresholds get logged ⚠️
--device.ssm.trajectories — says whether trajectories get logged (if false, only the extremal values and times are reported) 🎯
--device.ssm.range FLOAT — the detection range in meters. For vehicles below this distance from the equipped vehicle, SSM values are traced 📏
--device.ssm.extratime FLOAT — the time in seconds to be logged after a conflict is over. Required >0 if PET is to be calculated for crossing conflicts 👀
--device.ssm.mdrac.prt FLOAT — the perception reaction time for MDRAC computation 🧠
--device.ssm.file STR — give a global default filename for the SSM output 🗂️
--device.ssm.geo — whether to use coordinates of the original reference system in the output 🗺️
--device.ssm.write-positions — whether to write positions (coordinates) for each timestep 📍
--device.ssm.write-lane-positions — whether to write lanes and their positions for each timestep 🛣️
--device.ssm.write-na — whether to write conflict outputs with no data as NA values or just skip it 💀
--device.ssm.exclude-conflict-types STR — which conflicts get excluded from the log, based on the conflict type they've been classified as (a combination of values in 'ego', 'foe' , '', any numerical valid conflict type code). An empty value will log all of them, and 'ego'/'foe' refer to a certain conflict type subset 🙈

🎀 ToC Device Options 🎀

--device.toc.probability FLOAT — the probability for a vehicle to have a toc device 💖
--device.toc.explicit STR[] — assign a toc device to named vehicles ✨
--device.toc.deterministic — the toc devices are set deterministic using a fraction of 1000 🌟
--device.toc.manualType STR — vehicle type for the manual driving regime 🚙
--device.toc.automatedType STR — vehicle type for the automated driving regime 🤖
--device.toc.responseTime FLOAT — average response time a driver needs to take back control ⏱️
--device.toc.recoveryRate FLOAT — recovery rate for the driver's awareness after a ToC 🌱
--device.toc.lcAbstinence FLOAT — the attention level below which a driver restrains from performing lane changes (value in [0,1]) 🚫
--device.toc.initialAwareness FLOAT — the average awareness a driver has initially after a ToC (value in [0,1]) 🧠
--device.toc.mrmDecel FLOAT — the deceleration rate applied during a 'minimum risk maneuver' 🛑
--device.toc.dynamicToCThreshold FLOAT — the time the vehicle requires to have ahead of it to continue in automated mode. The default value of 0 means no dynamic triggering of ToCs 👑
--device.toc.dynamicMRMProbability FLOAT — the probability that a dynamically triggered TOR is not answered in time ⌛
--device.toc.mrmKeepRight — if true, the vehicle tries to change to the right during an MRM ➡️
--device.toc.mrmSafeSpot STR — if set, the vehicle tries to reach the given named stopping place during an MRM 🅿️
--device.toc.mrmSafeSpotDuration FLOAT — how long the vehicle stays at the safe spot after an MRM 🕐
--device.toc.maxPreparationAccel FLOAT — the maximal acceleration that may be applied during the ToC preparation phase 🚀
--device.toc.ogNewTimeHeadway FLOAT — timegap for the ToC preparation phase ⏳
--device.toc.ogNewSpaceHeadway FLOAT — extra spacing for the ToC preparation phase 📐
--device.toc.ogMaxDecel FLOAT — the maximal deceleration applied for establishing the increased gap in the ToC preparation phase 🛑
--device.toc.ogChangeRate FLOAT — rate of adaptation towards the increased headway during ToC preparation 🔄
--device.toc.useColorScheme — whether a coloring scheme shall be applied to indicate the different ToC stages 🎨
--device.toc.file STR — switches on output by specifying an output filename 📄

🧠 Driver State Device Options 🧠

--device.driverstate.probability FLOAT — the probability for a vehicle to have a driverstate device 💭
--device.driverstate.explicit STR[] — assign a driverstate device to named vehicles 💖
--device.driverstate.deterministic — the driverstate devices are set deterministic using a fraction of 1000 ✨
--device.driverstate.initialAwareness FLOAT — the initial value assigned to the driver's awareness 🌱
--device.driverstate.errorTimeScaleCoefficient FLOAT — the time scale for the error process ⏱️
--device.driverstate.errorNoiseIntensityCoefficient FLOAT — the noise intensity driving the error process 📈
--device.driverstate.speedDifferenceErrorCoefficient FLOAT — the general scaling coefficient for applying the error to the perceived speed difference (the error also scales with distance) 🚗
--device.driverstate.headwayErrorCoefficient FLOAT — the general scaling coefficient for applying the error to the perceived distance (the error also scales with distance) 📏
--device.driverstate.freeSpeedErrorCoefficient FLOAT — the general scaling coefficient for applying the error to the vehicle's own speed when driving without a leader (the error also scales with own speed) 🏎️
--device.driverstate.speedDifferenceChangePerceptionThreshold FLOAT — the base threshold for recognizing changes in the speed difference (the threshold also scales with distance) 👀
--device.driverstate.headwayChangePerceptionThreshold FLOAT — the base threshold for recognizing changes in the headway (the threshold also scales with distance) 🔍
--device.driverstate.minAwareness FLOAT — the minimal admissible value for the driver's awareness 🫶
--device.driverstate.maximalReactionTime FLOAT — the maximal reaction time (~action step length) induced by a decreased awareness level (it's reached for awareness=minAwareness) ⌛

🚨 Bluelight Device Options 🚨

--device.bluelight.probability FLOAT — the probability for a vehicle to have a bluelight device 🚔
--device.bluelight.explicit STR[] — assign a bluelight device to named vehicles ✨
--device.bluelight.deterministic — the bluelight devices are set deterministic using a fraction of 1000 💫
--device.bluelight.reactiondist FLOAT — set the distance at which other drivers react to the blue light and siren sound 🔊
--device.bluelight.mingapfactor FLOAT — reduce the minGap for reacting vehicles by the given factor 📉

FCD Device Options: 💖

--device.fcd.probability FLOAT — The probability for a vehicle to have a 'fcd' device.
--device.fcd.explicit STR[] — Assign a 'fcd' device to named vehicles.
--device.fcd.deterministic — The 'fcd' devices are set deterministic using a fraction of 1000.
--device.fcd.begin STR — Recording begin time for FCD-data.
--device.fcd.period STR — Recording period for FCD-data.
--device.fcd.radius FLOAT — Record objects in a radius around equipped vehicles.
--person-device.fcd.probability FLOAT — The probability for a person to have a 'fcd' device.
--person-device.fcd.explicit STR[] — Assign a 'fcd' device to named persons.
--person-device.fcd.deterministic — The 'fcd' devices are set deterministic using a fraction of 1000.
--person-device.fcd.period STR — Recording period for FCD-data.

ElecHybrid Device Options: ⚡

--device.elechybrid.probability FLOAT — The probability for a vehicle to have a 'elechybrid' device.
--device.elechybrid.explicit STR[] — Assign a 'elechybrid' device to named vehicles.
--device.elechybrid.deterministic — The 'elechybrid' devices are set deterministic using a fraction of 1000.

Taxi Device Options: 🚕

--device.taxi.probability FLOAT — The probability for a vehicle to have a 'taxi' device.
--device.taxi.explicit STR[] — Assign a 'taxi' device to named vehicles.
--device.taxi.deterministic — The 'taxi' devices are set deterministic using a fraction of 1000.
--device.taxi.dispatch-algorithm STR — The dispatch algorithm [greedy|greedyClosest|greedyShared|routeExtension|traci].
--device.taxi.dispatch-algorithm.output FILE — Write information from the dispatch algorithm to FILE.
--device.taxi.dispatch-algorithm.params STR — Load dispatch algorithm parameters in format KEY1:VALUE1[,KEY2:VALUE].
--device.taxi.dispatch-period TIME — The period between successive calls to the dispatcher.
--device.taxi.dispatch-keep-unreachable TIME — The time before aborting unreachable reservations.
--device.taxi.idle-algorithm STR — The behavior of idle taxis [stop|randomCircling|taxistand].
--device.taxi.idle-algorithm.output FILE — Write information from the idling algorithm to FILE.
--device.taxi.vclasses STR[] — Network permissions that can be accessed by taxis.

GLOSA Device Options: 🚦

--device.glosa.probability FLOAT — The probability for a vehicle to have a 'glosa' device.
--device.glosa.explicit STR[] — Assign a 'glosa' device to named vehicles.
--device.glosa.deterministic — The 'glosa' devices are set deterministic using a fraction of 1000.
--device.glosa.range FLOAT — The communication range to the traffic light.
--device.glosa.max-speedfactor FLOAT — The maximum speed factor when approaching a green light.
--device.glosa.min-speed FLOAT — Minimum speed when coasting towards a red light.
--device.glosa.add-switchtime FLOAT — Additional time the vehicle shall need to reach the intersection after the signal turns green.
--device.glosa.use-queue — Use queue in front of the tls for GLOSA calculation.
--device.glosa.override-safety — Override safety features - ignore the current light state, always follow GLOSA's predicted state.
--device.glosa.ignore-cfmodel — Vehicles follow a perfect speed calculation - ignore speed calculations from the CF model if not safety critical.

Tripinfo Device Options: 📝

--device.tripinfo.probability FLOAT — The probability for a vehicle to have a 'tripinfo' device.
--device.tripinfo.explicit STR[] — Assign a 'tripinfo' device to named vehicles.
--device.tripinfo.deterministic — The 'tripinfo' devices are set deterministic using a fraction of 1000.

Vehroutes Device Options: 🛣️

--device.vehroute.probability FLOAT — The probability for a vehicle to have a 'vehroute' device.
--device.vehroute.explicit STR[] — Assign a 'vehroute' device to named vehicles.
--device.vehroute.deterministic — The 'vehroute' devices are set deterministic using a fraction of 1000.

Friction Device Options: 🧊

--device.friction.probability FLOAT — The probability for a vehicle to have a 'friction' device.
--device.friction.explicit STR[] — Assign a 'friction' device to named vehicles.
--device.friction.deterministic — The 'friction' devices are set deterministic using a fraction of 1000.
--device.friction.stdDev FLOAT — The measurement noise parameter which can be applied to the friction device.
--device.friction.offset FLOAT — The measurement offset parameter which can be applied to the friction device -> e.g. to force false measurements.

FCD Replay Device Options: 🔁

--device.fcd-replay.probability FLOAT — The probability for a vehicle to have a 'fcd-replay' device.
--device.fcd-replay.explicit STR[] — Assign a 'fcd-replay' device to named vehicles.
--device.fcd-replay.deterministic — The 'fcd-replay' devices are set deterministic using a fraction of 1000.
--device.fcd-replay.file FILE — FCD file to read.

TraCI Server Options: 🖥️

--remote-port INT — Enables TraCI Server if set.
--num-clients INT — Expected number of connecting clients.

Mesoscopic Options: 🔬

--mesosim — Enables mesoscopic simulation.
--meso-edgelength FLOAT — Length of an edge segment in mesoscopic simulation.
--meso-tauff TIME — Factor for calculating the net free-free headway time.
--meso-taufj TIME — Factor for calculating the net free-jam headway time.
--meso-taujf TIME — Factor for calculating the jam-free headway time.
--meso-taujj TIME — Factor for calculating the jam-jam headway time.
--meso-jam-threshold FLOAT — Minimum percentage of occupied space to consider a segment jammed. A negative argument causes thresholds to be computed based on edge speed and tauff (default).
--meso-multi-queue — Enable multiple queues at edge ends.
--meso-lane-queue — Enable separate queues for every lane.
--meso-ignore-lanes-by-vclass STR[] — Do not build queues (or reduce capacity) for lanes allowing only the given vclasses.
--meso-junction-control — Enable mesoscopic traffic light and priority junction handling.
--meso-junction-control.limited — Enable mesoscopic traffic light and priority junction handling for saturated links. This prevents faulty traffic lights from hindering flow in low-traffic situations.
--meso-tls-penalty FLOAT — Apply scaled travel time penalties when driving across tls controlled junctions based on green split instead of checking actual phases.
--meso-tls-flow-penalty FLOAT — Apply scaled headway penalties when driving across tls controlled junctions based on green split instead of checking actual phases.
--meso-minor-penalty TIME — Apply fixed time penalty when driving across a minor link. When using --meso-junction-control.limited, the penalty is not applied whenever limited control is active.
--meso-overtaking — Enable mesoscopic overtaking.
--meso-recheck TIME — Time interval for rechecking insertion into the next segment after failure.
--meso-interpolate-pos — Enable mesoscopic position interpolation.

Random Number Options: 🎲

--random — Initialises the random number generator with the current system time.
--seed INT — Initialises the random number generator with the given value.
--thread-rngs INT — Number of pre-allocated random number generators to ensure repeatable multi-threaded simulations (should be at least the number of threads for repeatable simulations).

GUI Only Options: 🎨

-g, --gui-settings-file FILE — Load visualisation settings from FILE.
-Q, --quit-on-end — Quits the GUI when the simulation stops.
-G, --game — Start the GUI in gaming mode.
--game.mode STR — Select the game type ('tls', 'drt').
-S, --start — Start the simulation after loading.
-d, --delay FLOAT — Use FLOAT in ms as delay between simulation steps.
-B, --breakpoints STR[] — Use TIME[] as times when the simulation should halt.
-m, --edgedata-files FILE — Load edge/lane weights for visualization from FILE.
-N, --alternative-net-file FILE — Load a secondary road network for abstract visualization from FILE.
--selection-file FILE — Load pre-selected elements from FILE.
-D, --demo — Restart the simulation after ending (demo mode).
-T, --disable-textures — Do not load background pictures.
--registry-viewport — Load current viewport from registry.
--window-size STR[] — Create initial window with the given x,y size.
--window-pos STR[] — Create initial window at the given x,y position.
--tracker-interval TIME — The aggregation period for value tracker windows.
--osg-view — Start with an OpenSceneGraph view instead of the regular 2D view.
--gui-testing — Enable overlay for screen recognition.
--gui-testing-debug — Enable output messages during GUI-Testing.
--gui-testing.setting-output FILE — Save gui settings in the given settings output file.

EXAMPLES 🎀

Here are some examples, bestie:

sumo -b 0 -e 1000 -n net.xml -r routes.xml

start a simulation from time 0 to 1000 with given net and routes

sumo -c munich_config.cfg

start with a configuration file

sumo --help

print help

and that's the tea for now, but we're not done yet 💅✨

🐛 REPORTING BUGS 💖

okay bestie, found something cursed? it happens to everyone, no shame. tell the maintainers! 💅

bugs go here: <https://github.com/eclipse-sumo/sumo/issues>
wanna talk to actual humans instead: <sumo@dlr.de>

fr fr, the devs wanna hear about it. that's how the slay continues ✨

🌈 the build tea ☕

this is how the binary you're holding was compiled, and it's giving very specific:

Build features: Linux-6.8.0-139-generic x86_64 GNU 15.3.0 None
FMI Proj GUI Intl SWIG Eigen GDAL FFmpeg OSG GL2PS
Copyright (C) 2001-2026 German Aerospace Center (DLR) and others;
https://sumo.dlr.de

FMI, Proj, GUI, Intl, SWIG, Eigen, GDAL, FFmpeg, OSG, GL2PS — that's the whole roster, all present and accounted for 👑

📜 the legal bit (iykyk) 👑

Eclipse SUMO sumo 1.27.1 is part of SUMO. periodt.

this program and the stuff that ships with it? made available under the terms of the Eclipse Public License v2.0 that comes with this distribution — you can also grab it right here:

<https://www.eclipse.org/legal/epl-v20.html>

and ALSO 🌸, when the conditions for that availability set out in the Eclipse Public License 2.0 are satisfied, this program may be made available under these Secondary Licenses: the GNU General Public License, version 2 or later, which lives at

<https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html>

so the SPDX line is exactly this, no notes:

SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-or-later

🫶 two licenses, one absolute icon. do not lose this information, bestie, it's literally the receipts.

and that's the whole page, we ate and left no crumbs 🍓 this one's Eclipse SUMO sumo 1.27.1, from August 2026, and you'll find it filed under ECLIPSE(1) ✨ mwah 💖

📦 where this page comes from

ubuntu stonking: sumo 1.27.1+dfsg-1 · EPL-2.0 OR GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms