Extending agent-based simulation capabilities by coupling external models using FastAPI

Agent-based models (ABM) are a promising tool to study the emergent effects from decisions of heterogenous actors. However, due to the high computational complexity, many models face challenges in accurately capturing the actors’ decision-making processes.

To address this, we present a dedicated model coupling approach based on FastAPI¹, which allows to externalise complex decision-making logic to facilitate efficient simulations. We demonstrate such an interface developed for the open electricity market model AMIRIS²[1]. While AMIRIS is implemented in the Java-based framework FAME [2,3], the external model can be formulated in any language desired since communication between models is accomplished via HTTP requests with data in, e.g., JSON format. As part of the coupling workflow, an AMIRIS agent sends requests and receives response messages. The external model performs its calculation based on the message sent by the AMIRIS agent and optional additional data, e.g. from local files. AMIRIS waits for the external model’s response message and then resumes the simulation. This approach allows to couple a wide range of models. Here, we provide four different implementations.

First, we apply it to provide electricity price forecasts to an AMIRIS agent via an external machine-learning (ML) model [4]. In a stress test, the external model is called hourly with a payload of 16 time series of 168 timesteps each. The overhead resulting from communication between models has a negligible impact on runtime extension. The most expensive aspect is the call of the actual machine learning algorithm. In total, a yearly AMIRIS simulation in hourly resolution takes approximately 20 seconds if such an external model is employed, compared to 10 seconds for a standard run.

Second, we couple AMIRIS to an external GAMS-based heat pump dispatch optimization model. This allows us to analyse the impact of price-based heat pump operation on the wholesale electricity market [5]. AMIRIS periodically calls the external model which calculates the optimal heat pump electricity demand schedule based on the most recent simulated electricity prices. Finally, the demand profile is returned to AMIRIS where it impacts the upcoming market clearings.

Third, similarly to the previously described heat pump model, AMIRIS is coupled to an external python-based generic load shifting scheduling model. This incorporates technical constraints of a load shifting portfolio and seeks to minimize consumers overall power payment obligations, thereby allowing for the consideration of flexibly designed power tariffs as well as incorporating an estimate for the price repercussion of the flexible load [6].

Fourth, AMIRIS is coupled with ML-based demand forecasting, in turn built on household-level optimization models for PV and electric vehicles. This allows to combine the strengths of models on an individual level with a national simulation. Hourly forecasts are off by 5-8% and thus provide a rather accurate national demand.

We conclude that the proposed concept allows researchers to integrate any external model during simulation runtime, thereby extending the capabilities of AMIRIS. The setup can be easily adapted to accommodate various modelling approaches, thus extending the decision logic of ABM agents.

Acknowledgements

The authors would like to thank the German Federal Ministry of Education and Research (BMBF) for funding the FEAT project (01IS22073B), the German Federal Ministry of Economics and Technology (BMWK) for funding the EN4U project (03EI1029A) and the ERAFlex II project (03EI1033A), and the European Union for funding the TradeRES project (864276).

References

[1]    Schimeczek C, Nienhaus K, Frey U, Sperber E, Sarfarazi S, Nitsch F et al. AMIRIS: Agent-based Market model for the Investigation of Renewable and Integrated energy Systems. JOSS 2023;8(84):5041.

[2]    Schimeczek C, Deissenroth-Uhrig M, Frey U, Fuchs B, Ghazi AAE, Wetzel M et al. FAME-Core: An open Framework for distributed Agent-based Modelling of Energy systems. JOSS 2023;8(84):5087.

[3]    Nitsch F, Schimeczek C, Frey U, Fuchs B. FAME-Io: Configuration tools for complex agent-based simulations. JOSS 2023;8(84):4958.

[4]    Nitsch F, Schimeczek C, Bertsch V. Applying machine learning to electricity price forecasting in simulated energy market scenarios. Energy Reports 2024;12:5268–79.

[5]    Sperber E, Schimeczek C, Frey U, Cao KK, Bertsch V. Aligning heat pump operation with market signals: A win-win scenario for the electricity market and its actors? Energy Reports 2025;13:491–513.

[6]    Kochems J. Lastmanagementpotenziale im deutschen Stromsystem: Technische Universität Berlin; 2024.