The FirstOrderDynamics class represents the dynamics of the network. More...

#include <FirstOrderDynamics.hpp>

Inheritance diagram for dsf::mobility::FirstOrderDynamics:

Public Member Functions
	FirstOrderDynamics (RoadNetwork &&graph, bool useCache=false, std::optional< unsigned int > seed=std::nullopt)
	Construct a new FirstOrderDynamics object.
void	prepareNetwork (bool const bAdjustNodeCapacities=true, bool const bAutoMapStreetLanes=false, bool const bAutoAssignRoadPriorities=true, bool const bAutoInitTrafficLights=true)
	Automatically prepare the network for the simulation. This method calls the following methods in order:
void	setErrorProbability (double errorProbability)
	Set the error probability.
void	setPassageProbability (double passageProbability)
	Set the passage probability.
void	killStagnantAgents (double timeToleranceFactor=3.)
	Set the time tolerance factor for killing stagnant agents. An agent will be considered stagnant if it has not moved for timeToleranceFactor * std::ceil(street_length / street_maxSpeed) time units.
void	saveData (std::time_t const savingInterval, bool const saveAverageStats=false, bool const saveStreetData=false, bool const saveTravelData=false, bool const saveAgentData=false)
	Enable data saving (compatibility wrapper; persistence is handled by TrafficSimulator).
template<typename... TArgs>
void	setSpeedFunction (SpeedFunction const speedFunction, TArgs &&... args)
	Set the speed function. Options are:
void	setForcePriorities (bool const forcePriorities) noexcept
	Set the force priorities flag.
void	setUpdatePathsThrowOnEmpty (bool const throwOnEmpty) noexcept
	Set the update paths throw on empty flag.
void	setDataUpdatePeriod (Delay const dataUpdatePeriod) noexcept
	Set the data update period.
void	setMeanTravelDistance (double const meanTravelDistance)
	Set the mean distance travelled by a random agent. The distance will be sampled from an exponential distribution with this mean.
void	setMeanTravelTime (std::time_t const meanTravelTime) noexcept
	Set the mean travel time for random agents. The travel time will be sampled from an exponential distribution with this mean.
void	setUTurnPenaltyFactor (double uturnPenaltyFactor)
	Set the penalty factor applied to U-turns when choosing the next street.
void	setReinsertAgents (bool const reinsertAgents) noexcept
void	setIntelligentAgentsFraction (double const intelligentFraction)
	Set the fraction of intelligent agents.
void	setOrigins (std::unordered_map< Id, double > const &origins={})
	Set the origins.
void	setDestinations (std::unordered_map< Id, double > const &destinations)
	Set the destinations.
void	setDestinations (std::initializer_list< Id > destinations)
	Set the destinations.
void	setODs (std::vector< std::tuple< Id, Id, double > > const &ODs)
	Set the origin-destination pairs with their associated weights.
void	setConditionalODs (std::unordered_map< Id, std::tuple< double, std::vector< std::tuple< Id, double > > > > const &originToDestinations)
	Set the origin-destination pairs with their associated weights from a map of origin nodes to vectors of destination nodes and weights.
template<typename TContainer> requires (std::is_convertible_v<typename TContainer::value_type, Id>)
void	setDestinations (TContainer const &destinationNodes)
	Set the destinations.
void	importODsFromCSV (std::string_view const fileName, char const separator=';', bool const bEdges=true)
	Import origin-destination pairs from a CSV file. Possibilities are:
void	setTransitionMatrix (std::unordered_map< Id, std::unordered_map< Id, double > > const &transitionMatrix)
	Set the transition matrix used to route random agents.
void	importTransitionMatrixFromJSON (std::string_view const fileName)
	Import the transition matrix used to route random agents from a JSON file.
void	initTurnCounts ()
	Initialize the turn counts map.
void	resetTurnCounts ()
	Reset the turn counts map values to zero.
void	updatePaths ()
	Update the paths of the itineraries based on the given weight function.
void	addAgentsUniformly (std::size_t nAgents, std::optional< Id > itineraryId=std::nullopt)
	Add agents uniformly on the road network.
void	addAgent (std::unique_ptr< Agent > agent)
	Add an agent to the simulation.
void	addAgent (std::vector< std::shared_ptr< Itinerary > > const &trip, std::optional< Id > optSrcStreetId=std::nullopt)
	Add an agent to the simulation.
void	addAgent (std::shared_ptr< Itinerary > pItinerary=nullptr, std::optional< Id > optSrcStreetId=std::nullopt)
	Add an agent to the simulation.
void	addAgents (std::size_t const nAgents, AgentInsertionMethod const mode)
	Add agents to the simulation.
template<typename... TArgs> requires (std::is_constructible_v<Itinerary, TArgs...>)
void	addItinerary (TArgs &&... args)
	Add an itinerary.
void	addItinerary (std::shared_ptr< Itinerary > itinerary)
	Add an itinerary.
StepDataResult	evolve (StepDataRequest const &dataRequest={})
	Evolve the simulation.
void	optimizeTrafficLights (TrafficLightOptimization optimizationType=TrafficLightOptimization::DOUBLE_TAIL, const std::string &logFile=std::string(), double const percentage=0.3, double const threshold=1.3)
	Optimize the traffic lights by changing the green and red times.
auto const &	freeflowItineraries () const noexcept
	Get the free-flow itineraries.
auto	intelligentAgentsFraction () const noexcept
	Get the fraction of intelligent agents, i.e. following the updated paths.
auto const &	itineraries () const noexcept
	Get the itineraries.
auto const &	origins () const noexcept
	Get the origin nodes of the graph.
auto &	origins () noexcept
	Get the origin nodes of the graph.
auto const &	destinations () const noexcept
	Get the destination nodes of the graph.
auto &	destinations () noexcept
	Get the destination nodes of the graph.
auto const &	transitionMatrix () const noexcept
	Get the transition matrix used to route random agents.
const std::vector< std::unique_ptr< Agent > > &	agents () const noexcept
	Get the agents.
auto	nAgents () const
	Get the number of agents currently in the simulation.
auto	ghostAgents () const
	Get the number of ghost agents waiting to be inserted.
Measurement< double >	meanTravelTime (bool clearData=false)
	Get the mean travel time of the agents in \(s\).
Measurement< double >	meanTravelDistance (bool clearData=false)
	Get the mean travel distance of the agents in \(m\).
Measurement< double >	meanTravelSpeed (bool clearData=false)
	Get the mean travel speed of the agents in \(m/s\).
TurnCountsDict const &	turnCounts () const noexcept
	Get the turn counts of the agents.
std::unordered_map< Id, std::unordered_map< Id, double > > const	normalizedTurnCounts () const noexcept
	Get the normalized turn counts of the agents.
tbb::concurrent_unordered_map< Id, std::size_t >	originCounts (bool const bReset=true) noexcept
	Get the origin counts of the agents.
tbb::concurrent_unordered_map< Id, std::size_t >	destinationCounts (bool const bReset=true) noexcept
	Get the destination counts of the agents.
template<bool Normalized>
Measurement< double >	streetMeanDensity () const
	Get the mean density of the streets in \(m^{-1}\) or \(a.u.\) if Normalized.
Measurement< double >	streetMeanFlow () const
	Get the mean flow of the streets in \(s^{-1}\).
Measurement< double >	streetMeanFlow (double threshold, bool above) const
	Get the mean flow of the streets in \(s^{-1}\).
auto	agentStats () const noexcept
	Get agents stats from this Dynamics as the following tuple: (nAddedAgents, nInsertedAgents, nArrivedAgents, nKilledAgents, nAgents).
void	summary (std::ostream &os=std::cout) const
	Print a summary of the dynamics to an output stream.
Public Member Functions inherited from dsf::Dynamics< RoadNetwork >
	Dynamics (RoadNetwork &&graph, std::optional< unsigned int > seed=std::nullopt)
	Construct a new Dynamics object.
void	setSeed (unsigned int const seed) noexcept
	Set the seed for the random number generator.
void	setConcurrency (std::size_t const concurrency)
	Set the maximum number of threads to use for parallel execution.
auto	concurrency () const
	Get the current concurrency (number of threads configured in the task arena).
auto const &	graph () const
	Get the graph.
auto	time_step () const
	Get the current simulation time-step.

Protected Attributes
TurnCountsDict	m_turnCounts
tbb::concurrent_unordered_map< Id, std::unordered_map< Direction, double > >	m_queuesAtTrafficLights
tbb::concurrent_vector< std::pair< double, double > >	m_travelDTs
tbb::concurrent_vector< std::unique_ptr< Agent > >	m_agentsToReinsert
std::time_t	m_previousOptimizationTime {0}
std::optional< double >	m_errorProbability {std::nullopt}
std::optional< double >	m_passageProbability {std::nullopt}
std::optional< double >	m_meanTravelDistance {std::nullopt}
std::optional< std::time_t >	m_meanTravelTime {std::nullopt}
std::optional< Delay >	m_dataUpdatePeriod
bool	m_bCacheEnabled
std::optional< double >	m_timeToleranceFactor {std::nullopt}
bool	m_forcePriorities {false}
Protected Attributes inherited from dsf::Dynamics< RoadNetwork >
std::unique_ptr< RoadNetwork >	m_graph
tbb::task_arena	m_taskArena
std::mt19937_64	m_generator

Additional Inherited Members
Protected Member Functions inherited from dsf::Dynamics< RoadNetwork >
void	m_evolve ()

Detailed Description

The FirstOrderDynamics class represents the dynamics of the network.

Constructor & Destructor Documentation

◆ FirstOrderDynamics()

dsf::mobility::FirstOrderDynamics::FirstOrderDynamics	(	RoadNetwork &&	graph,
		bool	useCache = false,
		std::optional< unsigned int >	seed = std::nullopt )

Construct a new FirstOrderDynamics object.

Parameters

graph	The graph representing the network
useCache	If true, the cache is used (default is false)
seed	The seed for the random number generator (default is std::nullopt)

Member Function Documentation

◆ addAgent() [1/3]

void dsf::mobility::FirstOrderDynamics::addAgent	(	std::shared_ptr< Itinerary >	pItinerary = nullptr,
		std::optional< Id >	optSrcStreetId = std::nullopt )

Add an agent to the simulation.

Parameters

pItinerary std::shared_ptr to the itinerary

If pItinerary is nullptr, the agent will be added without an itinerary

Parameters

optSrcStreetId std::optional<Id> representing the source street id. If not provided, the source street will be selected randomly.

◆ addAgent() [2/3]

void dsf::mobility::FirstOrderDynamics::addAgent ( std::unique_ptr< Agent > agent )

Add an agent to the simulation.

Parameters

agent std::unique_ptr to the agent

◆ addAgent() [3/3]

void dsf::mobility::FirstOrderDynamics::addAgent	(	std::vector< std::shared_ptr< Itinerary > > const &	trip,
		std::optional< Id >	optSrcStreetId = std::nullopt )

Add an agent to the simulation.

Parameters

trip	std::vector of std::shared_ptr to the itineraries
optSrcStreetId	std::optional<Id> representing the source street id. If not provided, the source street will be selected randomly.

◆ addAgents()

void dsf::mobility::FirstOrderDynamics::addAgents	(	std::size_t const	nAgents,
		AgentInsertionMethod const	mode )

Add agents to the simulation.

Parameters

nAgents	The number of agents to add
mode	The method to use for adding the agents.Possible values are: ODS: Agents are generated according to the provided OD pairs RANDOM: Agents spwan randomly in the network and travel with no destination RANDOM_ODS: Agents are generated by randomly selecting their origin and destination according to the weights

◆ addAgentsUniformly()

void dsf::mobility::FirstOrderDynamics::addAgentsUniformly	(	std::size_t	nAgents,
		std::optional< Id >	itineraryId = std::nullopt )

Add agents uniformly on the road network.

Parameters

nAgents	The number of agents to add
itineraryId	The id of the itinerary to use (default is std::nullopt)

Exceptions

std::runtime_error If there are no itineraries

◆ addItinerary() [1/2]

void dsf::mobility::FirstOrderDynamics::addItinerary ( std::shared_ptr< Itinerary > itinerary )

Add an itinerary.

Parameters

itinerary std::unique_ptr to the itinerary

Exceptions

std::invalid_argument	If the itinerary already exists
std::invalid_argument	If the itinerary's destination is not a node of the graph

◆ addItinerary() [2/2]

template<typename... TArgs>
requires (std::is_constructible_v<Itinerary, TArgs...>)

void dsf::mobility::FirstOrderDynamics::addItinerary ( TArgs &&... args )

Add an itinerary.

Parameters

...args The arguments to construct the itinerary

The arguments must be compatible with any constructor of the Itinerary class

◆ agents()

const std::vector< std::unique_ptr< Agent > > & dsf::mobility::FirstOrderDynamics::agents ( ) const

inlinenoexcept

Get the agents.

Returns: const std::unordered_map<Id, Agent<Id>>&, The agents

◆ agentStats()

auto dsf::mobility::FirstOrderDynamics::agentStats ( ) const

inlinenoexcept

Get agents stats from this Dynamics as the following tuple: (nAddedAgents, nInsertedAgents, nArrivedAgents, nKilledAgents, nAgents).

Returns: std::tuple<std::size_t, std::size_t, std::size_t, std::size_t, std::size_t> The tuple containing the agents stats

◆ destinationCounts()

tbb::concurrent_unordered_map< Id, std::size_t > dsf::mobility::FirstOrderDynamics::destinationCounts ( bool const bReset = true )

noexcept

Get the destination counts of the agents.

Parameters

bReset If true, the destination counts are cleared (default is true)

◆ destinations() [1/2]

auto const & dsf::mobility::FirstOrderDynamics::destinations ( ) const

inlinenoexcept

Get the destination nodes of the graph.

Returns: std::vector<std::tuple<Id, double>> const& The destination nodes of the graph

◆ destinations() [2/2]

auto & dsf::mobility::FirstOrderDynamics::destinations ( )

inlinenoexcept

Get the destination nodes of the graph.

Returns: std::vector<std::tuple<Id, double>>>& The destination nodes of the graph

◆ evolve()

StepDataResult dsf::mobility::FirstOrderDynamics::evolve ( StepDataRequest const & dataRequest = {} )

Evolve the simulation.

Evolve the simulation by moving the agents and updating the travel times. In particular:

Move the first agent of each street queue, if possible, putting it in the next node
Move the agents from each node, if possible, putting them in the next street and giving them a speed. If the error probability is not zero, the agents can move to a random street. If the agent is in the destination node, it is removed from the simulation (and then reinserted if reinsert_agents is true)
Cycle over agents and update their times
Parameters

dataRequest The save/collection request for the current step

Returns
StepDataResult The collected data for the current step

◆ freeflowItineraries()

auto const & dsf::mobility::FirstOrderDynamics::freeflowItineraries ( ) const

inlinenoexcept

Get the free-flow itineraries.

Returns: const std::unordered_map<Id, std::shared_ptr<Itinerary>>&, The free-flow itineraries, i.e. the best paths computed at the first updatePaths() call for each itinerary

◆ ghostAgents()

auto dsf::mobility::FirstOrderDynamics::ghostAgents ( ) const

inline

Get the number of ghost agents waiting to be inserted.

Returns: std::size_t The number of ghost agents

◆ importODsFromCSV()

void dsf::mobility::FirstOrderDynamics::importODsFromCSV	(	std::string_view const	fileName,
		char const	separator = ';',
		bool const	bEdges = true )

Import origin-destination pairs from a CSV file. Possibilities are:

origin_id;destination_id;weight (for AgentInsertionMethod::ODS)
node_id;type;weight (for AgentInsertionMethod::RANDOM_ODS, where type is either "O" or "D")
origin_id;weight;destinations (for AgentInsertionMethod::CONDITIONAL_RANDOM_ODS, where destinations is a comma-separated list of destination_id:weight pairs)

◆ importTransitionMatrixFromJSON()

void dsf::mobility::FirstOrderDynamics::importTransitionMatrixFromJSON ( std::string_view const fileName )

Import the transition matrix used to route random agents from a JSON file.

Parameters

fileName The path of the JSON file

The file must contain an object whose keys are the current street ids and whose values are objects mapping the candidate next street ids to their probabilities, e.g.:

{
  "1042": { "1043": 0.6, "1055": 0.2 },
  "1043": { "1080": 1.0 }
}

Rows are not required to sum to 1: the probability of ending the trip is always inferred at runtime as one minus the sum of the other probabilities. The imported matrix is then passed to setTransitionMatrix, which validates it.

Exceptions

std::runtime_error	If the file cannot be parsed or has an invalid structure
std::invalid_argument	If a key is not a valid street id, if a probability is negative or if a row sums up to more than 1

◆ initTurnCounts()

void dsf::mobility::FirstOrderDynamics::initTurnCounts ( )

Initialize the turn counts map.

Exceptions

std::runtime_error if the turn counts map is already initialized

◆ intelligentAgentsFraction()

auto dsf::mobility::FirstOrderDynamics::intelligentAgentsFraction ( ) const

inlinenoexcept

Get the fraction of intelligent agents, i.e. following the updated paths.

Returns: double The fraction, in [0, 1]

◆ itineraries()

auto const & dsf::mobility::FirstOrderDynamics::itineraries ( ) const

inlinenoexcept

Get the itineraries.

Returns: const std::unordered_map<Id, Itinerary>&, The itineraries

◆ killStagnantAgents()

void dsf::mobility::FirstOrderDynamics::killStagnantAgents ( double timeToleranceFactor = 3. )

Set the time tolerance factor for killing stagnant agents. An agent will be considered stagnant if it has not moved for timeToleranceFactor * std::ceil(street_length / street_maxSpeed) time units.

Parameters

timeToleranceFactor The time tolerance factor

Exceptions

std::invalid_argument If the time tolerance factor is not positive

◆ meanTravelDistance()

Measurement< double > dsf::mobility::FirstOrderDynamics::meanTravelDistance ( bool clearData = false )

Get the mean travel distance of the agents in \(m\).

Parameters

clearData If true, the travel distances are cleared after the computation

Returns: Measurement<double> The mean travel distance of the agents and the standard deviation

◆ meanTravelSpeed()

Measurement< double > dsf::mobility::FirstOrderDynamics::meanTravelSpeed ( bool clearData = false )

Get the mean travel speed of the agents in \(m/s\).

Parameters

clearData If true, the travel times and distances are cleared after the computation

Returns: Measurement<double> The mean travel speed of the agents and the standard deviation

◆ meanTravelTime()

Measurement< double > dsf::mobility::FirstOrderDynamics::meanTravelTime ( bool clearData = false )

Get the mean travel time of the agents in \(s\).

Parameters

clearData If true, the travel times are cleared after the computation

Returns: Measurement<double> The mean travel time of the agents and the standard deviation

◆ nAgents()

auto dsf::mobility::FirstOrderDynamics::nAgents ( ) const

inline

Get the number of agents currently in the simulation.

Returns: std::size_t The number of agents

◆ normalizedTurnCounts()

std::unordered_map< Id, std::unordered_map< Id, double > > const dsf::mobility::FirstOrderDynamics::normalizedTurnCounts ( ) const

noexcept

Get the normalized turn counts of the agents.

Returns: const std::unordered_map<Id, std::unordered_map<Id, double>>& The normalized turn counts. The outer map's key is the street id, the inner map's key is the next street id and the value is the normalized number of counts

◆ optimizeTrafficLights()

void dsf::mobility::FirstOrderDynamics::optimizeTrafficLights	(	TrafficLightOptimization	optimizationType = TrafficLightOptimization::DOUBLE_TAIL,
		const std::string &	logFile = std::string(),
		double const	percentage = 0.3,
		double const	threshold = 1.3 )

Optimize the traffic lights by changing the green and red times.

Parameters

optimizationType	TrafficLightOptimization, The type of optimization. Default is DOUBLE_TAIL
logFile	The file into which write the logs (default is empty, meaning no logging)
percentage	double, the maximum amount (percentage) of the green time to change (default is 0.3)
threshold	double, The ratio between the self-density and neighbour density to trigger the non-local optimization (default is 1.3)

The local optimization is done by changing the green time of each traffic light, trying to make it proportional to the queue lengths at each phase. The non-local optimization is done by synchronizing the traffic lights which are congested over threshold.

◆ originCounts()

tbb::concurrent_unordered_map< Id, std::size_t > dsf::mobility::FirstOrderDynamics::originCounts ( bool const bReset = true )

noexcept

Get the origin counts of the agents.

Parameters

bReset If true, the origin counts are cleared (default is true)

◆ origins() [1/2]

auto const & dsf::mobility::FirstOrderDynamics::origins ( ) const

inlinenoexcept

Get the origin nodes of the graph.

Returns: std::vector<std::tuple<Id, double>> const& The origin nodes of the graph

◆ origins() [2/2]

auto & dsf::mobility::FirstOrderDynamics::origins ( )

inlinenoexcept

Get the origin nodes of the graph.

Returns: std::vector<std::tuple<Id, double>>& The origin nodes of the graph

◆ prepareNetwork()

void dsf::mobility::FirstOrderDynamics::prepareNetwork	(	bool const	bAdjustNodeCapacities = true,
		bool const	bAutoMapStreetLanes = false,
		bool const	bAutoAssignRoadPriorities = true,
		bool const	bAutoInitTrafficLights = true )

Automatically prepare the network for the simulation. This method calls the following methods in order:

RoadNetwork::adjustNodeCapacities()
RoadNetwork::autoMapStreetLanes()
RoadNetwork::autoAssignRoadPriorities()

RoadNetwork::autoInitTrafficLights()

Parameters

bAdjustNodeCapacities	If true, the nodes' capacities are adjusted using the streets' transport capacities (default is true)
bAutoMapStreetLanes	If true, the streets' lanes are automatically mapped using the network's topology (default is false)
bAutoAssignRoadPriorities	If true, the streets' priorities are automatically assigned using the network's topology (default is true)
bAutoInitTrafficLights	If true, the traffic lights' phases are automatically initialized using the streets' geometry (default is true)

◆ resetTurnCounts()

void dsf::mobility::FirstOrderDynamics::resetTurnCounts ( )

Reset the turn counts map values to zero.

Exceptions

std::runtime_error if the turn counts map is not initialized

◆ setConditionalODs()

void dsf::mobility::FirstOrderDynamics::setConditionalODs ( std::unordered_map< Id, std::tuple< double, std::vector< std::tuple< Id, double > > > > const & originToDestinations )

Set the origin-destination pairs with their associated weights from a map of origin nodes to vectors of destination nodes and weights.

Parameters

originToDestinations An unordered map where the keys are origin node ids and the values are origin weights and vectors of tuples (destination node id, weight)

◆ setDataUpdatePeriod()

void dsf::mobility::FirstOrderDynamics::setDataUpdatePeriod ( Delay const dataUpdatePeriod )

inlinenoexcept

Set the data update period.

Parameters

dataUpdatePeriod Delay, The period

Some data, i.e. the street queue lengths, are stored only after a fixed amount of time which is represented by this variable.

◆ setDestinations() [1/3]

void dsf::mobility::FirstOrderDynamics::setDestinations ( std::initializer_list< Id > destinations )

Set the destinations.

Parameters

destinations The destinations (as an initializer list)

◆ setDestinations() [2/3]

void dsf::mobility::FirstOrderDynamics::setDestinations ( std::unordered_map< Id, double > const & destinations )

Set the destinations.

Parameters

destinations The destinations

◆ setDestinations() [3/3]

template<typename TContainer>
requires (std::is_convertible_v<typename TContainer::value_type, Id>)

void dsf::mobility::FirstOrderDynamics::setDestinations ( TContainer const & destinationNodes )

Set the destinations.

Parameters

destinations A container of destination ids

The container must have a value_type convertible to Id and begin() and end() methods

◆ setErrorProbability()

void dsf::mobility::FirstOrderDynamics::setErrorProbability ( double errorProbability )

Set the error probability.

Parameters

errorProbability The error probability

Exceptions

std::invalid_argument If the error probability is not between 0 and 1

◆ setForcePriorities()

void dsf::mobility::FirstOrderDynamics::setForcePriorities ( bool const forcePriorities )

inlinenoexcept

Set the force priorities flag.

Parameters

forcePriorities The flag

If true, if an agent cannot move to the next street, the whole node is skipped

◆ setIntelligentAgentsFraction()

void dsf::mobility::FirstOrderDynamics::setIntelligentAgentsFraction ( double const intelligentFraction )

Set the fraction of intelligent agents.

Parameters

intelligentFraction The fraction, in [0, 1]

When it is added, each non-random agent is flagged as intelligent with this probability (default is 0, i.e. no intelligent agents). Intelligent agents follow the paths recomputed at each updatePaths() call, while the others route on the free-flow best paths (see freeflowItineraries()).

Exceptions

std::invalid_argument If the fraction is not in [0, 1]

◆ setMeanTravelDistance()

void dsf::mobility::FirstOrderDynamics::setMeanTravelDistance ( double const meanTravelDistance )

inline

Set the mean distance travelled by a random agent. The distance will be sampled from an exponential distribution with this mean.

Parameters

meanTravelDistance The mean distance

Exceptions

std::invalid_argument If the mean distance is negative

◆ setMeanTravelTime()

void dsf::mobility::FirstOrderDynamics::setMeanTravelTime ( std::time_t const meanTravelTime )

inlinenoexcept

Set the mean travel time for random agents. The travel time will be sampled from an exponential distribution with this mean.

Parameters

meanTravelTime The mean travel time

◆ setODs()

void dsf::mobility::FirstOrderDynamics::setODs ( std::vector< std::tuple< Id, Id, double > > const & ODs )

Set the origin-destination pairs with their associated weights.

Parameters

ODs	A vector of tuples (origin node id, destination node id, weight)

◆ setOrigins()

void dsf::mobility::FirstOrderDynamics::setOrigins ( std::unordered_map< Id, double > const & origins = {} )

Set the origins.

Parameters

origins The origin nodes

◆ setPassageProbability()

void dsf::mobility::FirstOrderDynamics::setPassageProbability ( double passageProbability )

Set the passage probability.

Parameters

passageProbability The passage probability

The passage probability is the probability of passing through a node It is useful in the case of random agents

◆ setSpeedFunction()

template<typename... TArgs>

void dsf::mobility::FirstOrderDynamics::setSpeedFunction	(	SpeedFunction const	speedFunction,
		TArgs &&...	args )

Set the speed function. Options are:

(LINEAR, alpha): speed = max_speed * (1 - alpha * moving_density), where alpha is a parameter in [0, 1) and moving_density = n_moving_agents / capacity (queued agents cost queue time instead, see RoadNetwork::setEdgeWeight)
(CONSTANT): speed = max_speed, i.e. agents always travel in free flow
(CUSTOM, func): speed = func(pointer to a street), where func is a callable provided by the user that takes the street's pointer.

◆ setTransitionMatrix()

void dsf::mobility::FirstOrderDynamics::setTransitionMatrix ( std::unordered_map< Id, std::unordered_map< Id, double > > const & transitionMatrix )

Set the transition matrix used to route random agents.

Parameters

transitionMatrix The transition matrix, i.e. a map whose outer key is the current street id, whose inner keys are the candidate next street ids and whose values are the corresponding probabilities

The probabilities of each row must sum up to at most 1: the missing mass is the probability that the agent ends its trip at that junction, which is inferred at runtime and must not be part of the given matrix. Streets which are not a key of the matrix keep the default uniform behaviour. Entries which cannot be used because the destination street is unknown or is not an outgoing edge of the source street's target node are dropped and reported as warnings, which reduces the row's total probability and thus increases the end probability accordingly. Forbidden turns and U-turns are handled differently: since random agents can never take them, their probability is instead redistributed proportionally among the other entries of the same row, so that the end probability is unaffected by their weights. If a row only contains forbidden-turn and/or U-turn entries, there is nothing to redistribute onto and the probability is dropped (reported as a warning) like any other unusable entry.

Exceptions

std::invalid_argument If a probability is negative or if a row sums up to more than 1

◆ setUpdatePathsThrowOnEmpty()

void dsf::mobility::FirstOrderDynamics::setUpdatePathsThrowOnEmpty ( bool const throwOnEmpty )

inlinenoexcept

Set the update paths throw on empty flag.

Parameters

throwOnEmpty The flag

If true, if an itinerary has an empty path when updating paths, an exception is thrown. If false, the itinerary is left unchanged.

◆ setUTurnPenaltyFactor()

void dsf::mobility::FirstOrderDynamics::setUTurnPenaltyFactor ( double uturnPenaltyFactor )

inline

Set the penalty factor applied to U-turns when choosing the next street.

Parameters

uturnPenaltyFactor The penalty factor, which must be positive.

Exceptions

std::invalid_argument If the penalty factor is not positive.

◆ streetMeanDensity()

template<bool Normalized>

Measurement< double > dsf::mobility::FirstOrderDynamics::streetMeanDensity ( ) const

inline

Get the mean density of the streets in \(m^{-1}\) or \(a.u.\) if Normalized.

Template Parameters

Normalized If true, the density is normalized by the street's capacity

Returns: Measurement<double> The mean density of the streets and the standard deviation

◆ streetMeanFlow() [1/2]

Measurement< double > dsf::mobility::FirstOrderDynamics::streetMeanFlow ( ) const

Get the mean flow of the streets in \(s^{-1}\).

The flow uses the speeds of the agents that left each street since the last data save (see evolve); reading it does not reset them.

Returns: Measurement<double> The mean flow of the streets and the standard deviation

◆ streetMeanFlow() [2/2]

Measurement< double > dsf::mobility::FirstOrderDynamics::streetMeanFlow	(	double	threshold,
		bool	above ) const

Get the mean flow of the streets in \(s^{-1}\).

Same speed samples as streetMeanFlow(); reading them does not reset them.

Parameters

threshold	The density threshold to consider
above	If true, the function returns the mean flow of the streets with a density above the threshold, otherwise below

Returns: Measurement<double> The mean flow of the streets and the standard deviation

◆ summary()

void dsf::mobility::FirstOrderDynamics::summary ( std::ostream & os = std::cout ) const

Print a summary of the dynamics to an output stream.

Parameters

os	The output stream to write to (default is std::cout)

The summary includes:

The RoadNetwork description (nodes, edges, capacity, intersections, traffic lights, roundabouts, coil sensors)
Number of inserted agents
Number of added agents
Number of arrived agents
Number of killed agents
Current number of agents in the simulation

◆ transitionMatrix()

auto const & dsf::mobility::FirstOrderDynamics::transitionMatrix ( ) const

inlinenoexcept

Get the transition matrix used to route random agents.

Returns: std::unordered_map<Id, std::unordered_map<Id, double>> const& The transition matrix. The outer key is the current street id, the inner key is the next street id and the value is the transition probability. It is empty if no transition matrix has been set.

◆ turnCounts()

TurnCountsDict const & dsf::mobility::FirstOrderDynamics::turnCounts ( ) const

inlinenoexcept

Get the turn counts of the agents.

Returns: const std::unordered_map<Id, std::unordered_map<Id, size_t>>& The turn counts. The outer map's key is the street id, the inner map's key is the next street id and the value is the number of counts

◆ updatePaths()

void dsf::mobility::FirstOrderDynamics::updatePaths ( )

Update the paths of the itineraries based on the given weight function.

Itineraries without a free-flow counterpart get one, copied from the freshly computed path. This snapshot is never updated afterwards, so the first call should happen on the empty network.

Exceptions

std::runtime_error if m_updatepathsThrowOnEmpty is true and an itinerary has an empty path

The documentation for this class was generated from the following files:

src/dsf/mobility/FirstOrderDynamics.hpp
src/dsf/mobility/FirstOrderDynamics.cpp

Public Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ FirstOrderDynamics()

Member Function Documentation

◆ addAgent() [1/3]

◆ addAgent() [2/3]

◆ addAgent() [3/3]

◆ addAgents()

◆ addAgentsUniformly()

◆ addItinerary() [1/2]

◆ addItinerary() [2/2]

◆ agents()

◆ agentStats()

◆ destinationCounts()

◆ destinations() [1/2]

◆ destinations() [2/2]

◆ evolve()

◆ freeflowItineraries()

◆ ghostAgents()

◆ importODsFromCSV()

◆ importTransitionMatrixFromJSON()

◆ initTurnCounts()

◆ intelligentAgentsFraction()

◆ itineraries()

◆ killStagnantAgents()

◆ meanTravelDistance()

◆ meanTravelSpeed()

◆ meanTravelTime()

◆ nAgents()

◆ normalizedTurnCounts()

◆ optimizeTrafficLights()

◆ originCounts()

◆ origins() [1/2]

◆ origins() [2/2]

◆ prepareNetwork()

◆ resetTurnCounts()

◆ setConditionalODs()

◆ setDataUpdatePeriod()

◆ setDestinations() [1/3]

◆ setDestinations() [2/3]

◆ setDestinations() [3/3]

◆ setErrorProbability()

◆ setForcePriorities()

◆ setIntelligentAgentsFraction()

◆ setMeanTravelDistance()

◆ setMeanTravelTime()

◆ setODs()

◆ setOrigins()

◆ setPassageProbability()

◆ setSpeedFunction()

◆ setTransitionMatrix()

◆ setUpdatePathsThrowOnEmpty()

◆ setUTurnPenaltyFactor()

◆ streetMeanDensity()

◆ streetMeanFlow() [1/2]

◆ streetMeanFlow() [2/2]

◆ summary()

◆ transitionMatrix()

◆ turnCounts()

◆ updatePaths()