{'fraction_non_alphanumeric': 0.02930599538403736, 'fraction_numerical': 0.004830658579786378, 'mean_word_length': 5.311653116531165, 'pattern_counts': {'":': 0, '<': 0, '<?xml version=': 0, '>': 0, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
MaaSSim -- agent-based two-sided mobility platform simulator

Two-sided mobility platforms, such as Uber and Lyft, widely emerged in the urban mobility landscape, bringing disruptive changes to transportation systems worldwide. This calls for a simulation framework where researchers from various and across disciplines may introduce models aimed at representing the dynamics of platform-driven urban mobility systems. In this work, we present MaaSSim, an agent-based simulator reproducing the transport system used by two kind of agents: (i) travellers, requesting to travel from their origin to destination at a given time, and (ii) drivers supplying their travel needs by offering them rides. An intermediate agent, the platform, allows demand to be matched with supply. Agents are decision makers, specifically, travellers may decide which mode they use or reject an incoming offer. Similarly, drivers may opt-out from the system or reject incoming requests. All of the above behaviours are modelled through user-defined modules, representing agents' taste variations (heterogeneity), their previous experiences (learning) and available information (system control). MaaSSim is an open-source library available at a public repository github.com/RafalKucharskiPK/MaaSSim, along with a set of tutorials and reproducible use-case scenarios.


Motivation and significance
Two-sided mobility platforms (like Uber and Lyft) match supply with demand in urban transportation systems. Users submit travel requests in real-time and are instantly matched with drivers, offering to take them to their desired destination. All parties are independent decision makers acting according to their individual, heterogeneous preferences and learning from past experiences. Travellers are free to select among competing platforms and travel modes, whereas drivers choose whether to work for the available platforms, their working hours and strategically select served requests to maximise revenues.
Each of these research domains involves a series of significant and challenging research questions. Answering each of which is non-trivial, yet the main challenge lays in representing the complete system with its (inter)dependencies and feedback loops, non-determinism and adaptive evolution. In the absence of an encompassing modelling framework, most studies have been limited to a single aspect, e.g. [18] focuses on travellers behaviour and neglects fleet operations, whereas [19] focuses on real-time fleet operations while neglecting the travellers decision process; [20] embeds shared taxi operations into a detailed traffic agent-based micro-simulation, while [13] relies on arbitrary grid network and focuses on income equity.
To this end, we provide a modular, extensible framework which contains the fundamental representation of key phenomena related to two-sided mobility platforms. The key contribution of our software is in advancing the state-of-the-art of agent-based transport models towards two-sided mobility platform systems by providing a framework for developing, testing and simulating platform operations under various settings. An extensive set of tutorials and sample experiments facilitates a fast learning curve for users of various background, while modular, extensible architecture allows for its seamless development.

Software description
MaaSSim is an agent-based simulator, reproducing the dynamics of two-sided mobility platforms in the context of urban transport networks. It models the behaviour and interactions of two kind of agents: (i) travellers, requesting to travel from their origin to destination at a given time, and (ii) drivers supplying their travel needs by offering them rides. The interactions between the two agent types are mediated by the platform, matching demand and supply. Both supply and demand are microscopic. For supply this pertains to the explicit representation of single vehicles and their movements in time and space (using a detailed road network graph), while for demand this pertains to exact trip request time and destinations defined at the graph node level. Agents are decision makers. Specifically, travellers may reject the incoming offer or decide to use another mode than those offered by the mobility platform altogether. Similarly, driver may opt-out of the system (stop providing service) or reject/accept incoming requests. Moreover, they may strategically re-position while being idle.
All of above behaviours are modelled through user-defined decision modules, by default deterministic, optionally probabilistic, representing agents' taste variations (heterogeneity), their previous experiences (learning) and available information (system control). Each simulation run results in two sets of outputs. The sequence of recorded space-time locations and statuses for simulated vehicles and travellers. These outputs are further synthesised into agent-level and system-wide KPIs for in-depth analyses.

Software Architecture
MaaSSim is a scalable, easy-to-use, modular, extensible python library. The main class is called with a configuration file (.json file) allowing to control the input (travel demand, fleet supply, road network) and simulation (e.g. event duration and their variability). External decision functions to reproduce desired agents' behaviour are passed by reference and can be user-defined ( fig. 1). A simulation corresponds to a single day, during which routines of interacting agents are processed ( fig. 2) with a Simpy discrete-event simulation framework [28]. The simulation outputs raw logs (where spatio-temporal stamps of consecutive events are stored for each agent) as well as aggregated reports.
MaaSSim allows to replicate simulations (to obtain meaningful distributions of random variables), explore multidimensional parameter grids in parallel (e.g. various travellers' value-of-time and fleet size combinations) and simulate day-to-day evolution until convergence. Independent simulation runs may be executed in parallel, distributing computation load over multiple threads. Listing 1 provides an overview of MaaSSim usage. Listing 1: MaaSSim usage at glance: starting from a single simulation, through modifying input and configuration, up to parallel experiment computation and user defined decision function.

Input
MaaSSim is controlled via .json file which configures the simulation and specifies input. Running the MaaSSim simulation requires: a) an urban road network graph (an instance of networkX DiGraph imported for the simulated urban area with OSMnx [29]), b) travel demand (pandas DataFrame with origin and destination nodes and departure time for each trip request) and c) supply specifications (drivers with their working shifts and initial locations). Both supply and demand may come from external data sources or be generated using internal MaaSSim procedures.

Agents
Three kind of MaaSSim agents (implemented as SimPy processes) interact with each other during the course of their daily routines ( fig. 2): • Travellers may be assigned to multiple platforms and submit request to all of them to choose the best offer amongst those. A traveller unsatisfied with previous experience may opt-out before requesting. When receiving an offer the traveller makes a decision whether to accept it or not. While accepting she/he walks to the pick-up point, waits until the driver arrives, travels to the drop-off point and walks to the final destination, which terminates traveller's daily routine.
• Drivers operate in a loop, queuing to the platform and serving matched requests until the end of their shift ( fig. 2). Along their routines, drivers decide whether to: opt out before starting a shift and not enter the platform at all; accept or reject the incoming requests and finally re-position after becoming idle.
• Platforms operate in an infinite loop during simulation. Whenever a trip is requested or a driver becomes idle (starts a shift or completes previous request), the platform matches a two-sided queue of travellers on one side and drivers on another. A generic algorithm, matching travellers to the closest idle driver, can be replaced by referencing to a user-defined function.

Decision modules
The central functionality of MaaSSim is representing agents' individual decision processes (marked with round boxes on fig. 2). To this end, we introduced an interface where default functions may be overwritten with user-defined modules and integrated within MaaSSim simulations. User-defined functions can use MaaSSim parameterization, internal objects and their attributes (e.g. individual preferences of agents) to reproduce the desired behaviour of: • drivers leaving the system (f driver out), accepting requests (f driver decline) and re-positioning (f driver repos), • travellers leaving the system (f trav out) and selecting among platforms and modes (f trav mode), • platform matching requests to drivers (f match).

Computation times
MaaSSim has been developed to facilitate the research and assessment of system operations rather than realtime applications. The focus of its development has therefore been on code clarity and its accessibility for a broad community. Notwithstanding, it remains efficient and allows to run real-size computations within reasonable times. For instance, simulating 1000 travellers over 4 hours for the city of Delft, Netherlands takes ca 70s. It requires 28 minutes to simulate the Amsterdam network for 8 hours with 5 000 travellers, whereas simulating 50 travellers in the small Nootdorp takes less than 2 seconds on MacBookPro 2019. Parallel computations on multiple threads allowed to run 2000 simulations of experiment from fig.4 in less than two hours.
The complexity grows with the number of travellers, drivers and platforms (while each agent adds a new routine, the number of possible interactions between travellers and drivers within the platform follows a quadratic pattern). Surprisingly, network size does not affect the computations, as long as the pre-computed distance matrix fits into memory. The computation times may of course increase significantly if complex decision modules are introduced (and executed along with each agent's routine).

Illustrative Examples
We illustrate MaaSSim modelling capabilities through a series of experiments where we simulate various system settings under a range of configurations.
We start with a single simulation, where 10 drivers serve 200 trip requests in Delft, the Netherlands. A single platform matches travellers to the closest drivers who meet at the pick-up point and travel together to the destination. We replicate non-deterministic trip request generation (origin, destination and time) to obtain meaningful results. We analyse them in terms of waiting times, a key performance indicator for both supply and demand. Both agent groups aim to minimise their waiting times, travellers to arrive faster at their destination and drivers to minimise their idle times and thus increase revenues. However the obtained spatial patterns reveal conflicting trends ( fig. 3). While traveller waiting times (left) are low in the Eastern parts and high in the Western parts of Delft, for drivers the opposite trend prevails (right). This reveals interesting interactions between agents and potentially conflicting interests.
Next, we examine the supply and demand interactions in various settings. We explore the scenario grid varying from low to high demand and supply levels ( fig. 4). The waiting time for travellers (left) is low when there are few travellers and many drivers. Conversely, drivers idle times decrease if fleet size is low (right). While this overall trend is expected, the magnitude and the sensitivity of these relations and their potential to result with feedback loops on both demand and supply sides of the two-sided market would not have been possible without their detailed modelling.
Such interaction between the supply and demand typically leads to questions about strategic behaviour, reinforced learning and system equilibria. We illustrate how MaaSSim supports answering those questions by means of a platform competition experiment. We consider a system where an existing platform with 20 drivers offers travellers a trip fare of 1.0 unit/km. We explore potential strategies for a new platform entering the market in terms of two key variables: fleet size (varying from 5 to 40 drivers) and fare (varying from 0.6 to 1.5 units/km). Figure 5 shows the mileage per driver (left) and total platform revenues (right) resulting from the combination of various strategies. The box plots denote means and distributions resulting from 20 replications.
Since in the above experiments the simulations are independent (unlike the reinforced learning, where agent decisions are dependent on their experience learned from previous simulation runs) we use parallel computations on multiple threads and collect results in a single file for analysis.
We illustrate the strategic learning of agents with a scenario where 100 drivers serve 200 travellers in a sequence of day-to-day simulations ( fig. 6). Apparently, the initial supply level is too high, resulting in short waiting times for travellers and low revenues for drivers. Unsatisfied drivers will opt out due to bad previous experiences (low income), adjusting the pool of drivers which decreases until, eventually, some drivers decide to return to the system (as they observe high revenues in the adjusted system). Such adaptation leads to system stabilisation, which may vary due to non-deterministic simulation settings (demand distributions and initial vehicle positions).
Finally, we demonstrate how ride-pooling is embedded with simulations on fig. 7, where we show a trajectory of a vehicle serving non-shared, private rides (left) and pooled-rides (right). Shared rides are here pre-computed with external ExMAS [18] algorithm relying on behavioural and system parameters to optimally match travellers into attractive pooled rides.

Impact
The emergence of two-sided mobility markets disrupts the transport landscape. Conventional models for transport planning and operations are focused on top-down planning of service lines, timetable and traffic control measures which are not directly suitable for capturing the double-sided dynamics of mobility on demand services. This calls for the development of models that explicitly account for both supply-side and demandside dynamics, as well as their interaction with the intermediate matching platform. In particular, in order to capture the bottom-up emerging order resulting from two-sided mobility, it is essential to revise the modelling approach of key elements of the transport system: demand (which is now inherently microscopic), supply (which has become a decision maker) and a road network (which capacity and congestion are no longer a single pivot variable of assignment models) along with a new agent, the platform, which orchestrates supply and demand interaction and which might be subject to regulation. For example, New York City has introduced regulations pertaining to guaranteed minimum wage for ride-hailing drivers, entry caps and maximum empty vehicle-kilometre requirements [30]. There is therefore a need for a simulation model that facilitates the design and assessment of such policies as well as business models, prior to their implementation.
A wide array of research questions has consequently emerged, ranging from traffic flow, labour economics, real-time control, optimisation to travel behaviour. This bursting stream of research calls for the development of a unifying simulation framework under which emerging models, algorithms and approaches may be integrated. Recent changes are disruptive enough to justify a new framework, designed to reproduce the dynamics associated with a two-sided platform.
Furthermore, the already interdisciplinary field of transportation science has recently gained increasing interest from various fields such as complex network theory, system dynamics, social networks, marketing economics and computational physics. This makes it particularly timely to support a fast learning-curve by offering a quick, minimal setup to reproduce the basic dynamics of two-sided mobility platforms. To allow researchers to contribute in their domain, the software has to be modular and require minimal knowledge on other modules while allowing to enrich the overall experimental analysis.
MaaSSim is not intended for the complete modelling of transport systems for which there is abundance of mature and developed frameworks, both commercial (like PTV Visum, CUBE, Emme) and open source (like MatSim [31], SUMO [32], DynaMIT [33], SimMobility [34] etc.). Instead, the objective of MaaSSim is to support researches with modelling and reproducing the emerging phenomena taking place in the context of two-sided mobility platform and analyse their disruptive potential for urban transport systems.

Conclusion
The overarching objective underlying the development of MaaSSim is to allow researchers to focus on their partial models and integrate them within the simulation framework, allowing a group of interdisciplinary researchers to share expertise from their fields. For instance, MaaSSim has been instrumental in the scientific discovery process of supply-side dynamics and the fleet size attained in equilibrium in a decentralised bottomup mobility platform context. This research resulted with a novel service supplier (i.e. driver) learning and choice model [35] which can be now reused for studying platform pricing strategies, re-positioning algorithms or travellers mode-choices.
MaaSSim provides an extensible, easy-to-use simulation platform allowing for user-defined representation of two-sided mobility platform that can support a variety of research interests. MaaSSim is an open-source library available through the pip installer as well as from public repository, where it comes along with a set of tutorials and applicable use-cases. With the above set of experiments, coupled with reproducible jupyter notebooks stored on repository, the reader can get an impression of the range of MaaSSim applications and start developing their own experiments. In particular, explore own networks (queried from OpenStreetMap with [29]) and run the experiments with their own tailored configuration.

Conflict of Interest
We confirm that there are no known conflicts of interest associated with this publication and there has been no significant financial support for this work that could have influenced its outcome.