BeforeIT.jl: High-Performance Agent-Based Macroeconomics Made Easy
Authors: Adriano Meligrana, Mitja Devetak, Steven Hoekstra, Oliver Reiter, Enrico Minnella, Sebastian Poledna, Marco Bardoscia, Aldo Glielmo
Organizations: University of Turin, Turin, Italy · Paris 1 Panthéon-Sorbonne University, Paris, France · Complexity Science Hub, Vienna, Austria · Supply Chain Intelligence Institute Austria, Vienna, Austria · International Institute for Applied Systems Analysis (IIASA), Vienna, Austria · Applied Research Team, Directorate General for Information Technology, Banca d’Italia, Rome, Italy
BeforeIT is an open-source software for building and simulating state-of-the-art macroeconomic agent-based models (macro ABMs) based on the recently introduced macro ABM developed in [1] and here referred to as the base model. Written in Julia, it combines extraordinary computational efficiency with user-friendliness and extensibility. We present the main structure of the software, demonstrate its ease of use with illustrative examples, and benchmark its performance. Our benchmarks demonstrate that the base model built with BeforeIT is orders of magnitude faster than its original Matlab implementation, while achieving performance comparable to a highly optimised HPC implementation. Furthermore, we show how BeforeIT supports an easy construction of model variants such as the 'CANVAS' model of [2], how these variants can be evaluated at scale via an automated multicountry forecasting pipeline, and how the entire simulation can be automatically differentiated. BeforeIT is designed to facilitate reproducibility, extensibility, and experimentation. As the first open-source, industry-grade software to build macro ABMs, BeforeIT can significantly foster collaboration and innovation in the field of agent-based macroeconomic modelling. The package, along with its documentation, is freely available at https://github.com/bancaditalia/BeforeIT.jl under the Apache 2.0 license.
Figures & tables
Figure 1: Logo of the package. BeforeIT stands for B ehavioural e conomic fore casting by the IT research unit of the Bank of It aly. The agents in the ‘it’ monogram exemplify the agent-based nature of the simulation method. The name of the package also refers to the forecasting possibilities offered by the package, as in predicting a phenomenon before it happens .
Figure 2: Illustration of the workflow and main objects of the software . The constructor Model takes as input the two dictionaries parameters and initial_conditions , returning an object named model . This model object is composed of distinct objects representing the different agents of the economy, such as gov and firms and three other objects that do not represent agents but store properties and aggregate variables, i.e., prop , data and agg . The model object serves as input for run! , which iterates over T steps, while a collection of independently initialised models serves as input for ensemblerun! , which performs n_sims independent Monte Carlo runs. Simulation results are stored in the model object for a single run, or in the model_vec object for multiple runs, both of which allow easy inspection and visualisation of attributes for any agent type as well as of the aggregate variables tracked during the simulation. Similarly, we can inspect any attribute of any of the agent classes. A simulation run simply loops over the function step! . One step consists of a series of well-defined function calls updating specific attributes of certain agent types, making up a modular and transparent simulation process.
Figure 3: A benchmark of the computational efficiency for different implementations. Mean time to run one step of the model calibrated on the Austrian economy with around 8 000 agents and 8 million agents using the original Matlab code, the C code generated by the Matlab Coder toolkit, the HPC implementation and BeforeIT . The benchmarks were executed on Linux x86_64 with an AMD Ryzen 5 5600H CPU and 16 GB of RAM, except for the HPC results, which were only estimated from [ 29 ] .
Figure 4: A simple script and its resulting graphs. The left panel shows a minimal script to run the model. We import the package, load the original parametrisation for Austria in the first quarter of 2010, and specify a given number of quarters to simulate. Then we call the Model function eight times, one for each Monte Carlo run, and finally the ensemblerun! function. Illustrative charts of some variables within model_vector are shown in the right panel. Solid lines are averages across the eight simulations, while semi-transparent regions span one standard deviation.
Figure 5: A script for shocked simulations and its resulting graph. The top panel illustrates the usage of the interface to run simulations with shocks. One simply defines a callable struct and passes it to the function ensemblerun! as the shock! keyword argument. The effect of the simulated consumption shock on the GDP (ratio of shocked over baseline) is presented in the bottom panel. Solid lines are averages across the 64 simulations, while semi-transparent regions span the standard error.
Figure 8: GDP optimisation trajectories by gradient method. Mean percentage GDP growth over 10 held-out random seeds along the optimisation, for an objective with horizons of one quarter (left) and four quarters (right). The Mooncake pathwise automatic gradient is compared against central finite differences computed in 64-bit and 128-bit floating-point precision, each with the relative steps h=ε1/3 and h=ε1/2 . Over one quarter, trajectories corresponding to 64-bit and 128-bit numerical gradients with h=ε1/2 overlap with the trajectory corresponding to automatic gradient, while over four quarters trajectories corresponding to every numerical gradient starkly depart from it.
Figure 9: Performance of gradient computation. Wall-clock time to compute the gradient of the objective with respect to an increasing subset of the model parameters, comparing the Mooncake automatic gradient against central finite differences.
Figure 11: RMSE improvement of ModelGR over a univariate AR benchmark. Each cell shows (RMSEAR−RMSEABM)×100 over a four-quarter horizon, averaged over all quarters from 2010Q1 to 2019Q4. Blue cells indicate that the ABM produces lower forecast errors than the AR; red cells indicate the opposite. Stars denote significance levels of the Diebold–Mariano, whose null hypothesis is that the two models have equal predictive accuracy ( ∗p<0.1 , ∗∗p<0.05 , ∗∗∗p<0.01 ).
Agent-based modeling simulates how interacting, heterogeneous entities and their environments produce patterns in social, economic, biological, and engineered systems.
Institute of Economics and L’EMbeDS2026 Sant’Anna School of Advanced Studies, Pisa, Italy · GREDEG, CNRS, Université Côte d’Azur Sophia Antipolis, France · Maastricht University Maastricht, The Netherlands
Institute of Economics and L'EMbeDS, Sant'Anna School of Advanced Studies · Institute of Economics and L’EMbeDS, Sant’Anna School of Advanced Studies, Pisa, Italy · Swiss Finance Institute and University of Geneve +1