copan:LPJmL: a new hybrid modelling framework for dynamic land use and agricultural management

Dynamic Global Vegetation Models (DGVMs) are established in environmental and agricultural sciences for many purposes, e.g., modelling plant growth and productivity, water and carbon cycles, and biosphere-climate interactions. Nevertheless, DGVMs are still rather limited in terms of simulating mutual interactions between biospheric and human processes. While DGVMs such as the Lund Potsdam Jena managed Land (LPJmL) model have been successfully connected to Integrated Assessment Models (IAMs), the model couplings often remain loose and static over the simulation period. The copan:LPJmL modelling framework is an extension of the copan:CORE framework for integrated and dynamic human-Earth system modelling, and addresses this issue by integrating LPJmL via a new interface, consisting of an LPJmL coupling library and a Python library pycoupler, which together enable LPJmL inputs and outputs to be coupled in copan:LPJmL during the simulation period. It uses the copan:CORE entities and integrates the coupled data into the World (simulation space as a whole) and the (grid) Cell entity, allowing other entities such as Individuals, e.g., for agent-based modelling (ABM), to access them. Besides ABM, this framework allows for a broad range of modelling approaches to be represented with copan:LPJmL, of which we introduce three examples: (1) The model of Integrated Social-Ecological Resilient Land Systems (InSEEDS), which uses a classical ABM approach to model management decisions by farmers, (2) an adaption of an established crop calendar model (Crop Calendar), and (3) a novel Large Language Model (LLM)-driven ABM approach (LLM Fertilization).

1 Introduction

The Anthropocene is a new epoch in the evolution of the Earth system characterized by increasingly strong and entangled coevolutionary dynamics of biogeophysical Earth system processes with human societies (Steffen et al., 2011; Schellnhuber, 1999; Crutzen, 2002). The recognition of biogeophysical and social processes as intertwined has emerged from historical developments in the field of Earth System Science. While James Lovelock already published the Gaia hypothesis in the early 1970s (Lovelock and Margulis, 1974), the broader scientific uptake of the term “Earth System Science” took place in the 1980s and 1990s (Lenton, 2016; Steffen et al., 2020). Central publications in this decade, such as the Bretherton Diagram (National Research Council, 1986) and the Brundtland report (Holdgate, 1987), acknowledge that human societies are tightly connected to Earth system dynamics. Followed by the realisation that (some) human societies now act as the major driving force of change on our planet (Steffen et al., 2011), while at the same time being shaped and impacted by the ecological conditions they are embedded in (Rockström et al., 2009), diverse novel conceptualisations of this intertwinedness, like the “technosphere” (Rosol et al., 2017) have emerged.

The consideration of the role of humans in the Earth System has thus progressed towards a coevolutionary, bidirectional approach, now evident in different strands of simulation modelling that can be summarised under the term World-Earth (System) modelling (WEM) or integrated human-Earth system modelling, with the entirety of human societies being referred to as the World (Beckage et al., 2020; Donges et al., 2021). WEM can be understood as a specific strand of social–ecological systems (SES) modelling that explicitly focuses on representing bidirectional feedbacks between human societies and the Earth system at regional to global scales (Preiser et al., 2018; Donges et al., 2021). There is growing research calling for and adopting a social-ecological, integrated perspective of humans embedded in the Earth System (e.g., (Donges et al., 2017; Schill et al., 2019; Beckage et al., 2020; Farahbakhsh et al., 2022; Beckage et al., 2022; Moore et al., 2022; Gerten et al., 2018). Different modelling communities approach this integration in distinct ways, and focus on different aspects of social-ecological dynamics. One central challenge of these efforts is moving beyond simple proof-of-concept models towards more complex, integrated models (Beckage et al., 2020).

Land systems are a key example of the inherently coevolutionary nature of social-ecological interactions in World-Earth Systems (Meyfroidt et al., 2022). Agricultural production is the single largest driver of transgressions of multiple planetary boundaries: land-system change, freshwater use, biogeochemical flows and biosphere integrity (Campbell et al., 2017), also contributing to the transgression of other planetary boundaries, such as climate change. In socio-ecological terms, global food demand drives responses in land use and production, including cropland and pasture expansion, and intensification through management practices such as irrigation and fertilization, and the reorganization of supply chains through trade. On the production side, farmers' management decisions, such as the use of crop rotations, cover cropping, reduced tillage, and integrated pest management can significantly influence the adverse environmental impacts that manifest themselves in the transgression of planetary boundaries (Gerten et al., 2020). Improved knowledge about the dynamic and coevolutionary development of agricultural systems at spatial scales from local to global is therefore imperative to foster our understanding of fundamental Anthropocene dynamics.

Land use systems alone have been a research subject in Earth system science for years, leading to their incorporation into DGVMs (such as LPJmL), crop models (e.g., DSSAT) as well as Earth System Models (ESMs, (e.g. MPI-ESM)) (Foley et al., 2005; Bondeau et al., 2007; Jones et al., 2003; Reick et al., 2013). Specific (such as tillage) or bundled management practices (like conservation agriculture) have been represented in detail and studied in local and global applications of such models (Herzfeld et al., 2021; Ngwira et al., 2014). Additionally, more holistic applications have been carried out, e.g., to show the potential of maintaining multiple planetary boundaries while feeding 10 billion people (Springmann et al., 2018; Gerten et al., 2020). However, the most important factor in implementing such measures or achieving such goals has been neglected: Humans are often merely represented as biophysical “disturbance” factors. This way, their decision-making capacities and social-psychological and socio-cultural complexities are therefore underrepresented, with many assumptions and dynamics, for example on land management and land use, remaining rather static (Schellnhuber, 1999; Rounsevell et al., 2014; Beckage et al., 2022). IAMs make it possible to simulate and optimize certain land use dimensions under a set of “human boundary conditions”, such as Shared Socioeconomic Pathways (SSP) scenarios (Dietrich et al., 2019). Through the application of macroeconomic and energy-economic optimization approaches, many IAMs reduce the complexity of human behaviour to predefined scenarios or boundary conditions, thereby excluding key dimensions of human decision-making uncertainty (Beck and Krueger, 2016; Asefi-Najafabady et al., 2021; Koasidis et al., 2023). While the SSP1 and SSP2 scenarios presented in the Sixth IPCC Assessment Report are considered economically feasible within IAMs, their assumptions regarding social-ecological feasibility – such as behavioural adaptation and governance dynamics – remain subject to significant uncertainty (IPCC, 2023; Schleussner et al., 2024; Krawczyk and Braun, 2025). Furthermore, these scenarios lack the fully coupled feedbacks of societies with the Earth system, i.e. the coevolution inherent in the underlying dynamics that is currently not representable endogenously with the majority of existing modelling approaches (Schlüter et al., 2012; Calvin and Bond-Lamberty, 2018).

To address this gap, Donges et al. (2020) introduced the copan:CORE modelling framework, which supports the development of World-Earth models (WEMs). WEMs are characterised by the explicit and bidirectional coupling of social and Earth system processes, enabling the coevolution of human and natural systems to be represented within a single modelling framework. They aim to go beyond traditional IAMs by incorporating human agency, social heterogeneity, and feedbacks between human decisions and biophysical dynamics (Mathias et al., 2020). A modelling framework is a software or conceptual infrastructure that provides the structure, components, and tools needed to build and run models, without being a single model itself. Copan:CORE provides the components and structures required to build WEMs. It consists of entities, such as a simulation cell or individuals, that interact with each other via various processes (Donges et al., 2020). The latter are categorized by three overlapping process taxa, representing biogeophysical and biogeochemical (ENV, e.g. biophysical conditions, crop growth), socio-metabolic (MET, e.g. crop harvest, fertilization) and socio-cultural processes (CUL, e.g., governance, social learning, social norms dynamics, or individual cognitive-behavioural processes like attitude formation) (Donges et al., 2021). We here have advanced the copan:CORE framework by integrating LPJmL as the ENV taxon (Schaphoff et al., 2018; von Bloh et al., 2018; Lutz et al., 2019), through which we can represent diverse natural as well as managed land systems, such as forests, grassland, and cropland (Sakschewski et al., 2016; Wirth et al., 2024b; Braakhekke et al., 2019; Rolinski et al., 2018; Porwollik et al., 2021; Jägermeyr et al., 2015; Minoli et al., 2022a) and link them bidirectionally to social processes that can be of economic nature but also go beyond that, for example including behavioural change, collective decision-making or political processes. Based on this, MET and CUL-based components of different modelling approaches can be realised by applying copan:LPJmL to represent various dimensions of social-ecological systems. By building on the diverse entities and process/model templates of copan:CORE, complex and detailed systems can be integrated to map underlying dynamics such as human, social, and societal processes using ABMs, dynamical system, or rule-based approaches.

In this paper, we introduce the copan:LPJmL modelling framework as a flexible and extensible platform for the development of WEMs, including a process-based DGVM Earth in a land system context. To demonstrate its applicability and versatility, we present three example applications:

1. InSEEDS, a global agent-based framework for simulating the adoption of regenerative agricultural practices by farmer agents (Schwarz et al., 2025);

2. Crop Calendar, an integrated (in runtime calculation) update of the rule-based model published by Minoli et al. (2019, 2022a); and

3. LLM fertilization, representing the application of crop fertilizer by LLM farmer agents. These examples illustrate how copan:LPJmL enables the integration of diverse socio-cultural and socio-metabolic processes with detailed Earth system dynamics.

2 Framework description

copan:LPJmL is a newly developed, enhanced WEM framework that integrates the DGVM LPJmL and the existing open modelling framework copan:CORE, thereby creating a modelling environment in which biophysical Earth-system and social world processes can be represented and bidirectionally linked to enable fully integrated and global gridded social-ecological modelling. It is designed to bring together the details and complexity of a process-based land biosphere model with the flexibility of an open modelling framework, thereby enabling the build-up of new types of integrated models. It allows selection from various modelling approaches such as agent-based, rule-based, dynamical system, or data-driven (statistical). copan:CORE forms the core framework in which the modular structure and building blocks, such as basic entities, are defined that can interact with each other. In copan:LPJmL, LPJmL is currently integrated via annual coupling to represent processes of the ENV taxon, with future development aiming to implement more frequent coupling intervals, ranging from monthly to daily. This is facilitated by LPJmL itself, which has been extended with a coupler library that is available in LPJmL from version 5.6 onwards, and applied in copan:LPJmL via the Python interface pycoupler (Breier and von Bloh, 2025).

Figure 1 Basic scheme of copan:LPJmL featuring the global grid, the process taxonomy as well as main entities with the three application examples: InSEEDS, Crop Calendar, and LLM Fertilization.

2.1 The CORE framework

copan:CORE, introduced by Donges et al. (2020), has established a novel systematic approach for building WEMs in a Python-based modelling environment with its corresponding Python library pycopancore. All copan:CORE model elements are represented as modular, object-oriented entities. These include agents (such as households, firms, or governments), social institutions, components of the Earth system or even more abstract entities such as a rulebook (basis for Crop Calendar). Additional entities can be flexibly introduced using the framework. In copan:CORE, each of these entities is involved in model processes that can be categorized by applying the aforementioned taxonomy system described by Donges et al. (2021) (ENV, MET and CUL). Another essential feature of copan:CORE is its support for heterogeneous agent populations and scalable network structures that define the relationships and interactions among agents, referred to as Individuals, and between agents and their linked entities. Besides Individuals these available entities in copan:CORE are the simulation space, the World, the underlying elemental spatial units, the Cells, the Social Systems such as countries or cities (Donges et al., 2020). Recently, Bechthold et al. (2025) added an additional Group entity as a social structure in which Individuals can organize themselves. In contrast to social systems, groups are not tied to a specific location, are loosely connected, and share only certain (temporary) characteristics, such as social norms. For copan:LPJmL, this variety is especially valuable, as the underlying hierarchies and networks provide a basic, real-life reflecting structure that aligns well with the simulation space (world) of LPJmL, in which Cells also reflect the elementary spatial unit of simulation. This way, the framework can represent the LPJmL organisational structure within the copan:CORE World. The library, pycopancore, also included model components, models and studies outside of the CORE definition (Bechthold et al., 2024). Within the process of building new software around copan:CORE, such as copan:LPJmL, this structure was reorganised to distinguish the CORE from other software and components related to copan:CORE, leaving only the components used by Donges et al. (2020) as an exemplary modelling approach (Breier et al., 2025b).

2.2 LPJmL as a model component

The DGVM LPJmL simulates the carbon, nitrogen, water and energy cycles of the terrestrial biosphere in coupling with the growth and productivity of natural and agricultural ecosystems, forced by climate, crop distribution, and other globally gridded input data (Schaphoff et al., 2018; von Bloh et al., 2018; Wirth et al., 2024a). It can represent various agricultural management practices (see Sect. 2.4) that requires additional information on the spatial and temporal distribution of management systems (Lutz et al., 2019; Porwollik et al., 2021; Jägermeyr et al., 2015; Herzfeld et al., 2021; Minoli et al., 2022a; Jägermeyr et al., 2016; Heinke et al., 2023). The smallest entity representing these processes is a grid cell, by default with a spatial extent of 0.5×0.5°, such that 67 420 cells represent the land surface globally. This spatial resolution reflects the design of LPJmL as a global-scale model that aims to capture large-scale biophysical dynamics while maintaining computational tractability. At this scale, individual grid cells represent aggregated socio-ecological systems rather than single land holdings or individual actors. In the current example applications, one representative agent is associated with each grid cell, which can be interpreted as representing the aggregated behaviour of multiple real-world actors within that region. However, the copan:LPJmL framework does not restrict the number of agents per grid cell. Applied models can introduce multiple agents per cell, represent heterogeneous actor types, or implement social interaction networks within and across cells. In this way, the spatial resolution of the biophysical LPJmL model can be combined with finer-grained representations of social processes depending on the research question and data availability. Plants are modelled according to the concept of Plant Functional Types (PFT) (Smith et al., 1993). The same principle is applied to Crop Functional Types (CFT) used for modelling agriculture on prescribed shares of each cell, called stands (Bondeau et al., 2007). copan:LPJmL introduces LPJmL as a new model component that covers the ENV taxon. It represents the LPJmL model as a World entity W_LPJmL (LPJmL simulation space, i.e. global), that integrates the coupled LPJmL model

$$\begin{array}{}\text{(1)}& {\mathcal{W}}_{\text{LPJmL}}=(\text{LPJmL},\mathit{\{}{C}_i\mid i=\mathrm{1},\mathrm{2},\mathrm{\dots },n\mathit{\left\}}\right)\end{array}$$

and its corresponding Cell entities C_LPJmL as shown in Fig. 2 following the concept of Donges et al. (2020). C_LPJmL includes the input and output of LPJmL for the cell as well as the grid information (longitude, latitude) and a network of its neighbouring cells 𝒩(C_i):

$$\begin{array}{}\text{(2)}& C_i=(\text{input},\text{output},\text{grid},\mathcal{N}(C_i\left)\right),\end{array}$$

where 𝒩(C_i) is defined as

$$\begin{array}{}\text{(3)}& \mathcal{N}\left(C_i\right)=\mathit{\{}{C}_j\mid d(C_i,C_j)\le r,j\ne i\text{ and }{C}_j\in {\mathcal{W}}_{\text{LPJmL}}\mathit{\}}\end{array}$$

and is calculated based on the grid information of each cell, with d(C_i,C_j) denoting the Euclidean distance between cell centroids, and $r=\sqrt{\mathrm{2}}\cdot \mathrm{0.5}\mathit{°}$ corresponding to the maximum distance between adjacent cells in the 0.5° grid (including diagonal neighbours). In the copan:LPJmL implementation, the World entity stores global LPJmL input, output, and grid information, while the associated Cell entities provide access to the corresponding spatial subsets of these data. This structure allows processes to operate either at the global (World) level or at the level of individual spatial units (Cell), enabling both aggregated and local interactions between biophysical and social model components. The specific technical implementation of these data structures and their efficient handling is documented in the copan:LPJmL software repository (Breier et al., 2025d).

Figure 2 Stylised flow chart of the integrated copan:LPJmL WEM framework. The orange highlighting indicates the parts and attributes that can be modified, extended or added. This applies to each entity type represented within its structural hierarchy and modelling interfaces of the framework described in detail in Sect. 2.2. “A WEM model” can be implemented by using and/or extending the World and corresponding Cell entities and by creating, for example, Individual A and B with distinct features and processes (a). The entities are hierarchically linked, while their interactions and processes are defined within the respective coupled model implementation. The three dots indicate that entities and attributes can be further extended. By creating A_WEM_model_config.yaml, those can be set up and added to the LPJmL configuration (LPJmLConfig) in which further simulation parameters and settings are specified (b). The coupled simulation is started based on the generated <sim_name>_config.json file (c). The LPJmLCoupler handles the coupling between LPJmL (Earth) and “A WEM model” by receiving and sending coupled data on an annual basis. The circular arrows represent the annual exchange of coupled LPJmL input and output data. “A WEM model” can compute intra-annual processes based on coupled LPJmL output to generate new coupled LPJmL input for closed feedback loops throughout the simulation period.

2.3 Bidirectional coupling with LPJmL

To enable a bidirectional, annual data coupling, LPJmL has been extended such that input and output data can be exchanged via TCP/IP socket connections during runtime. This option is now available for all inputs and outputs in the LPJmL configuration. During preprocessing, this configuration incorporates additional model settings such as the specification of coupled inputs and outputs. An excerpt of such a configuration with coupled inputs and outputs is shown as in Listing A1, also containing additional information such as the name of the coupled model, the start year of coupling, as well as the hostname and the port number of the coupled model. The coupling itself is provided by the LPJmL internal coupler library, which was implemented to encapsulate any socket communication in LPJmL. The coupling follows a prescribed protocol, as described in Listing A1 of the Appendix.

Conversely, to enable simple and practical coupling with LPJmL, we have developed pycoupler, a Python interface that provides tools around the coupling as well as handling of LPJmL in Python environments (Fig. 2). It serves as a configuration interface for coupled as well as stand-alone LPJmL simulations as well as functionality to send and receive xarray-based data objects from LPJmL. The coupling follows the prescribed coupling protocol, for which pycoupler contains the module LPJmLCoupler. The protocol is provided in detail in Listing A1 of the Appendix. With LPJmLCoupler, LPJmL is coupled on the Python side, and both sending and receiving methods are provided. It creates the underlying data structures (input, output, grid, country, etc.) and in the case of input data, initialises it with data read in at the start of the simulation. While all static data (e.g., grid, country) are only sent at the start of the simulation, time transient LPJmL output data is received from LPJmL on an annual basis and updated during simulation time via pycoupler (Sect. 2.3). Likewise, the input data can be changed within copan:LPJmL and sent back to LPJmL vice versa. pycoupler also allows for configuring (coupled) LPJmL simulations by providing an LPJmLConfig module, which simplifies reading, handling, modifying and writing of LPJmL configurations, the files of which are subsequently used to run the corresponding LPJmL simulations following Breier et al. (2024). Sending and receiving data is possible during the runtime of LPJmL on an annual basis. After a defined coupling year, LPJmL waits until the required input data is sent via LPJmLCoupler to continue the simulation until the end of the year to send back the output data. For the following years, the procedure is repeated. For a coupled simulation, the modules are usually applied together and in sequence in an individual run script. This way pycoupler supports a wide range of simulation and coupling setups. The pycoupler package is available on GitHub with more detailed function documentation and examples (Breier and von Bloh, 2025). Further technical details of the coupling implementation are documented in the software repository. Beyond that, pycoupler serves further utility functions around LPJmL, such as getting the neighbour cells of a cell or subsetting the grid for country-specific LPJmL simulations.

2.4 Development of WEMs with copan:LPJmL

The copan:LPJmL framework with its corresponding pycopanlpjml library unites all presented software components pycopancore (Sect. 2.1), LPJmL (Sect. 2.2) including the coupler library and the Python interface pycoupler (Sect. 2.3). For model developers, copan:LPJmL provides the hierarchical structure of entities illustrated in Fig. 2. The framework defines the global World entity and its associated Cell entities as the spatial unit structure and interface to LPJmL. Additional entities such as Individuals (e.g. farmer agents in an ABM) can be defined and linked to these spatial units. Model logic is implemented through initialisation and update methods that define how entities interact and evolve. Concrete application examples for this are presented in Sect. 3. All model parameters and settings can be specified via the corresponding model configuration files, which are combined with the LPJmL configuration to form a complete simulation setup, shown in Listing A2. Each configuration defines a specific simulation experiment that can be executed using pycoupler, enabling the coupled execution of the specific model that is implemented in the copan:LPJmL framework and LPJmL (Listing A3). With this structure, copan:LPJmL provides a modelling framework that enables researchers from diverse disciplinary fields to engage in modelling human-environmental interactions in the land-use sector. It allows users to specify custom decision rules, agent interactions, or feedback mechanisms, without requiring modification of the LPJmL model. This lowers the entry barrier and fosters interoperability, supporting a wide range of applications and interdisciplinary collaboration.

Within copan:LPJmL, LPJmL, the DGVM, defines the spatial scope and spatial resolution in this setup. It constitutes the ENV taxon of the WEM, and is complemented by the taxa MET and optionally CUL (Fig. 1). While MET processes are typically represented in many integrated modelling approches (i.e., IAMs), the CUL taxon is, as indicated in Sect. 1, often neglected (Schlüter et al., 2017; Beckage et al., 2022). We here provide a platform to include and explicitly represent these social processes of different actors and their interactions that influence environmental dynamics, for example, through land-use and agricultural management decisions that affect the inputs to the ENV component and its feedback to the CUL taxon. It facilitates the representation of “the social” from different perspectives. The CUL taxon can cover individual decision-making, social learning, but also economic dynamics, policy-making, and much more. A broader discussion of the types of social and decision-making processes that can be represented within this framework is provided in Sect. 4. Within the copan:LPJmL framework, MET and CUL processes can be represented with the full flexibility of copan:CORE. Their potential interactions with ENV are bound to the data interface of the terrestrial Earth, the inputs and outputs of LPJmL (Sect. 2.3). These are, on the one hand, the exposed inputs, represented in the World and Cell entity as an input attribute. In general, all available time-variable inputs in LPJmL can be exposed via pycoupler and thus coupled, an overview is given in Table 1.

Table 1 Overview and categorization of key inputs to LPJmL (ENV).

A corresponding change to one of these inputs, which is applied in LPJmL in the following year, results in a corresponding biophysical response that is reflected in the outputs. Vice versa, the range of available LPJmL outputs can be utilized in the MET and CUL taxon via the output attribute in World and Cell to inform and shape the respective processes. Here, too, all outputs are available in copan:LPJmL, the most important of which are listed in Table 2.

Table 2 Overview and categorization of key LPJmL outputs (ENV).

In principle, inputs can be extended, for example, by converting further parameters or settings into inputs. Any state variable or flux can also be written as an output, providing even more opportunities for model coupling. By design, copan:LPJmL allows the integration of a broad range of modelling paradigms of different domains that represent socio-ecological dynamics and feedbacks at varying levels of complexity and abstraction. Table 3 shows an overview of approaches that potentially could be represented in CUL and MET using copan:LPJmL. These include ABMs for simulating heterogeneous actors and interactions, rule-based systems for capturing institutional or behavioural heuristics, optimisation-based approaches for identifying efficient or goal-oriented management strategies, and surrogate or machine learning models for data-driven decision-making. System Dynamics models can be incorporated by formulating their underlying equation systems within the Dynamical Systems paradigm, ensuring compatibility with its feedback-oriented architecture. The flexibility enables the exploration of diverse real-world processes ranging from farmer decision-making to governance interventions.

(Schwarz et al., 2025)(Murray-Rust et al., 2014)(Wens et al., 2020; Huber et al., 2022)(Schrieks et al., 2021; Kreibich et al., 2025)(Minoli et al., 2022a, 2019)(Liang et al., 2021; Verburg and Overmars, 2009)(Szalai et al., 2014; Li et al., 2021)(Dietrich et al., 2019; Krey et al., 2020; Stehfest, 2014)(Blanco-Gutiérrez et al., 2013; Bodirsky et al., 2012; Beier et al., 2025)(Doelman et al., 2020; Bauer et al., 2020)(Bauch et al., 2016)(Horsevad et al., 2022)(Bury et al., 2019)(Liu et al., 2023)(Natel et al., 2025)(Kou-Giesbrecht et al., 2024; Dantas de Paula et al., 2020)(Zeng et al., 2025)

Table 3 Modelling paradigms and application domains supported by copan:LPJmL, with representative examples.

In addition, the framework supports a wide range of application areas that interact with the land system, in particular its ecological conditions, and resources. This can well result in more complex (social) structures in which, for example, only a first layer of agents interacts with the land system, while other actors are only connected to them, as in a supply and demand model for agricultural products involving farmers, food producers, and consumers. In general, potential domains are land-use change, agricultural management, climate adaptation, food-water-energy dynamics, policy evaluation, or socio-ecological transitions (Table 3). Through the modular interface and configurable data exchange with LPJmL, copan:LPJmL can serve as a backbone for integrated assessments across spatial scales and decision contexts.

3 Application examples

In order to illustrate a broad range of modelling approches that can be covered using copan:LPJmL, we present in the following three different representative applications examples of varying complexity, which are based on the different model paradigms and application areas shown in Table 3. While those examples give a taste of the possibilities of copan:LPJmL, they are not exhaustive, and many more applications of the framework are possible.

3.1 InSEEDS: a new agent-based World-Earth model

3.1.1 Modelling approach

In the field of SES science, different modelling approaches have emerged to capture the intertwined dynamics between human and biophysical spheres (Farahbakhsh et al., 2022; Anderies et al., 2023; Ye et al., 2024). Arguably, the most prominent approach to social-ecological modelling, ABM, is ideal to be used for modelling with copan:LPJmL (Rounsevell et al., 2012; Filatova et al., 2013; Schulze et al., 2017; Donges et al., 2020). ABMs simulate interactions between agents and their environments over time. These agents can represent individuals, households, organizations, or other entities. The simulation of these micro-level interactions gives rise to different macro-level outcomes, like spatial adoption patterns of a certain land use (Murray-Rust et al., 2014). Several features of ABMs make them a particularly useful methodological choice for the investigation of SES. SES are often understood as complex adaptive systems and therefore are inherently characterized by dynamical adaptation to changing behaviors and environments (Preiser et al., 2018). Furthermore, ABMs facilitate the study of macro-level phenomena emerging through micro-level dynamics. Lastly, ABMs are able to capture agent heterogeneity in human and biophysical spheres (Schlüter et al., 2021).

3.1.2 Model design

InSEEDS, described in detail in Schwarz et al. (2025) and implemented in Breier et al. (2025c), is a WEM created using the copan:LPJmL framework that uses an ABM component to capture farmer agent decision-making (Fig. 3). InSEEDS was originally designed to investigate the SES dynamics at play in transitions from conventional farming to regenerative farming practices such as conservation tillage. The CUL taxon comprises farmer management decision-making processes that are based purely on social interactions (i.e., evaluation of social norms) as well as information obtained from social-ecological processes (i.e., observing the environment). The social network of farmers forms the basis for these social dynamics and is initialised based on the LPJmL model grid (Sect. 2.2). In this realisation, one representative farmer agent is assigned to each cell. This means that each farmer has a maximum of eight direct neighbours who form their neighbourhood, which is currently the only explicitly represented social network (Eq. 3). However, this neighbourhood structure can be extended or complemented by additional non-local networks at regional or global scales. Such networks follow the implementation of acquaintance networks in copan:CORE (Donges et al., 2020) and can, for example, represent groups of agents distributed globally or within specific regions. An example of an implementation of a social-ecological feedback for a farmer in InSEEDS is given in Fig. 4. It shows a simple attitude formation process of farmer agents as an evaluation of their farming performance. In this realisation, farming performance is measured using the average crop yield and soil carbon content at different points in time. It is assumed that farmers have perfect knowledge of both variables in order to enable a preferably deterministic behaviour for analysis purposes only. copan:LPJmL allows for a generic processing of any LPJmL output, like agricultural soil carbon or CFT-specific crop yield demonstrates the flexibility copan:LPJmL provides in combination with the multiple features of xarray in subsetting and aggregating the underlying data. Thereby, it enables direct feedback functions to be set up to simulate important social-ecological aspects, such as farmers' attitudes towards their land.

Figure 3 Detailed scheme of InSEEDS highlighted in Fig. 1 representing the feedback mechanisms among the taxons ENV, MET and CUL. Individuals who are either of type pioneer or of type traditionalist observe crop yields and soil carbon and make decisions on conservation/conventional tillage to then be re-evaluated again.

Figure 4 Social-ecological processes and feedbacks in copan:LPJmL. (a) shows an example as a subset of InSEEDS – a farmer agent estimates their attitude toward their land based on two ENV variables (LPJmL output, see Sect. 2.3). The agent compares the topsoil carbon content and average crop yield between simulation steps. (b) shows a similar process in Crop Calendar in which the calendar is informed by processed climate data to estimate the ideal sowing dates for the next year. Social and ecological processes are highlighted in red and blue.

Such processes are part of the MET taxon, constituting the cross-section of socio-cultural and biophysical processes. Figure 4a shows a typical example of an observation of ecological variables, as well as the initiation of potential management decisions: Information on average crop yield and topsoil carbon content is calculated by the LPJmL ENV component and provided via the output attribute in the cell to farmer agents within a MET process. Vice versa, farmers' decisions are forwarded to LPJmL as input for the simulation via the MET component. Following the agent-based logic, the current main actors in the InSEEDS model are individual Farmer agents. The Farmer agent class itself is a child class of the Individual agent class in the copan:CORE modelling framework, inheriting the logic of Individuals described in (Donges et al., 2020). As an additional property of the Farmer, we introduce two agent-functional types (AFTs) (Arneth et al., 2014), a traditionalist and a pioneer farmer, who differ in their respective weighting of different parameters in the decision-making function (Fig. 4. The decision-making process is based on a formalisation of the Theory of Planned Behaviour originally described by Ajzen (1985). In principle, the decision-making process can be replaced by processes from other theories as well which is discussed in Sect. 4.

3.1.3 Example simulation results

InSEEDS can simulate social-ecological model dynamics on a wide spectrum of scales up to global scale. Analysis possibilities include distributed and accumulated social and ecological outcomes of variables such as attitude, social norm, or soil carbon, crop yield, or even adoption patterns of certain management practices. InSEEDS is the first model realisation using copan:LPJmL that simulates the aforementioned coevolutionary social-ecological dynamics through closed feedback loops. Figure 5 illustrates the underlying coevolution via three variables: The top row (a) shows the spatio-temporal dynamics of management practice adoption globally. The middle and lower row (b, c) depict the biophysical response of these behaviour changes in topsoil carbon content and average crop yield, compared to a business-as-usual simulation. In some areas, such as Kazakhstan, the spreading of conservation tillage and the underlying coevolution is particularly evident. Here, the adoption started in the southern regions and spread north-eastwards with moderate increases in soil carbon and significant increases in average crop yield. This synergistic effect results in a certain irreversibility in the modelled system. In our simulation, we find that in many regions, the adoption of conservation tillage has a positive effect on these variables, even though the results vary strongly at the local level. To better understand the underlying dynamics of specific cases, a more regional perspective is needed, which can be found together with the decision equations, parameterisation, parameter sensitivity, and detailed simulation results on coevolutionary model dynamics in Schwarz et al. (2025).

The development of InSEEDS is currently in an early phase. Future projects such as mapping non-local networks, social systems with multiple layers of complexity, and more social-ecological feedback processes can build on this approach. copan:CORE as described by Donges et al. (2020) provides entities, networks and components to achieve this. At this point, at the latest, the connection to the IAMs and the existing paradigmatic problems as described in (Sect. 1), such as missing closed social-ecological feedback loops can be drawn. By explicitly representing such closed social–ecological feedbacks, InSEEDS and the underlying copan:LPJmL framework provide a platform to explore the coevolution of social decision-making and environmental dynamics, offering new opportunities to investigate adaptive land-use transitions and management responses under changing environmental conditions.

Figure 5 InSEEDS simulation of (a) global spreading of conservation tillage represented as years since last management switch (backwards from simulation end year 2100). The adoption and spatial spreading of conservation tillage is depicted in orange, and conventional farming adoption in blue. If the saturation of both colours decreases over time, this indicates that there will be no further change in strategy. Vice versa, the more saturated the colour, the more recent the change. (b) and (c) show the corresponding changes in topsoil carbon content and average crop yield in 2100 compared to a simulation without management changes (business-as-usual) until 2100.

3.2 Integrated rule-based approaches: Crop calendar

3.2.1 Modelling approach

In many land-use and agricultural systems, management decisions are not made by autonomous agents, but instead follow fixed logics, institutional guidelines, or context-dependent thresholds. These RBMs operate via explicit if–then conditions, fuzzy logic or temporal schedules, allowing for transparent and interpretable decision structures (Arnold et al., 2018; Adriaenssens et al., 2004; Moore et al., 2014). Their structured logic makes them particularly suitable for encoding expert knowledge, empirical heuristics, or scenario-specific governance interventions, especially when interactions between agents are minimal or absent. As such, RBMs offer an efficient and reproducible way to represent adaptive but non-agentive processes across socio-environmental domains. Nevertheless, the boundaries are fluid, and rule-based and agent-based systems often overlap. While global, top-down approaches with Boolean logic can be clearly assigned to RBMs, there are bottom-up, autonomous approaches, such as cellular automata, that can be located between these paradigms (Li et al., 2016). Within copan:LPJmL, the RBM paradigm is particularly useful when system feedbacks should arise directly from dynamic ENV quantities – such as climate or resource availability – rather than from emergent behaviour. This makes them well-suited to simulate adaptive but non-agentic responses to environmental change.

Figure 6 Detailed scheme of the crop calendar implementation highlighted in Fig. 1 and Minoli et al. (2022a) representing the feedback mechanisms between the taxons ENV and MET. Climate data is forwarded by LPJmL to be used by the Crop Calendar to determine sowing and harvest dates for the upcoming year. Under changing climatic conditions, choosing the right sowing and harvesting times is crucial for maximizing crop yields, indicated by the grey and orange maize plants.

3.2.2 Model design

The adjustment of growing seasons in response to changes in climatic conditions is such an example and a central element in agricultural adaptation strategies. While changes in sowing dates may already be implemented by the farmers based on their experience (Waha et al., 2012), cultivar choices are subject to availability and breeding (Zabel et al., 2021). Minoli et al. (2019) proposed a modelling approach for simulating changes in growing seasons based on changes in climatic conditions only. This approach was used to create climate-scenario-specific time series of sowing dates and cultivar parameters as inputs for simulations with LPJmL (Minoli et al., 2022a). Implementing the algorithms of Minoli et al. (2019) using copan:LPJmL allows for a flexible application of adaptive growing seasons during runtime without requiring to previously compute growing seasons and corresponding crop parameters for each climate scenario (Breier et al., 2025a). In this setup, which is exemplary for rule-based management decisions, LPJmL passes only climate information as output to the growing season rules, which represent the MET taxon (Fig. 6). A CUL taxon is not involved in this setup, as there is no interaction between individual rule-based decision-making per crop and grid cell. To compute the required multi-year averages of monthly temperature and precipitation, the data is stored over a 10-year rolling window in the world's and cell's output attribute, updated annually via pycoupler, and continuously averaged during the simulation. Together with a vectorised global xarray-based implementation of the rule set at World level this approach is comparatively concise and computationally efficient compared to its reference (Minoli et al., 2022b). Figure 4b shows the corresponding processes of the Crop Calendar rule-based model logic.

3.2.3 Example simulation results

To verify the suitability of copan:LPJmL as a framework for Crop Calendar, it was implemented in its entirety and applied with one new climate input data set (SSP460, climate model: IPSL-CM6A-LR) from ISIMIP3b (Lange et al., 2024) to reproduce the original approach from Minoli et al. (2022a). Similar to this study, we conducted a comparison of recent and future (2080–2099) sowing and harvest dates for two important crop types, maize and temperate cereals (Fig. 7). For maize, the implementation dynamically adapts sowing dates in response to climatic changes, enabling earlier sowing in large areas of the temperate latitudes (Fig. 7a), while in the tropical regions, patterns are more heterogeneous, with both earlier and later sowing, depending on local conditions. Maturity dates (Fig. 7b) show greater spatial variability, often, but not always, following the pattern of earlier sowing. In some cases (e.g., India and China), maturity is reached later despite earlier sowing.

For temperate cereals, two varieties – a spring and a winter variety – are distinguished, which are sown in different seasons. The model not only adapts sowing dates for each variety but also allows for variety switching based on climate thresholds. While major variety switches remain rare due to modest warming, the model captures spatially nuanced shifts in sowing timing, with earlier sowing in parts of Canada, Europe, Russia, China, and India, and later sowing in eastern Europe and the USA. Maturity dates shift accordingly, with earlier maturity in the USA and southern Europe, and later dates, especially in higher latitudes.

These changes emerge from the dynamic rule-based responses to the climate input as indicated in Fig. B1a and b, showing the change in average annual temperature and annual precipitation between the recent and future time steps. For example, increases in spring temperatures extend the viable growing season and enable earlier sowing in temperature-sensitive regions. The calculation of the maturity date involves a multi-step approach (Minoli et al., 2019 for more details): (i) climate-sensitive harvest rule classification and (ii) harvest date and reason determination based on thresholds such as wet season or the warmest days. Figure B1c–f shows that harvest rules for maize shift the harvest reason in response to climate change, for instance, a transition in harvest reason from “mid temperature/precipitation” to “high temperature/precipitation” in South America, and from “mid temperature/mixed” to “high temperature/mixed” in parts of the USA and China (Fig. B1c and d). Although this is only a comparison between two time steps, the underlying runtime algorithm provides insight into each simulation year.

The results demonstrate that the copan:LPJmL-based crop calendar implementation successfully reproduces the climate-responsive adaptation of sowing and maturity dates of Minoli et al. (2019). However, unlike the reference implementation of Minoli et al. (2019), which requires additional preprocessing steps of the corresponding data products, the copan:LPJmL-based implementation enables a direct, runtime calculation of sowing and harvest dates under changing conditions. This makes the system more suitable for ensemble climate simulations or further SES applications in models such as InSEEDS, where crop production needs to coevolve endogenously to changing biophysical conditions.

Finally, this approach can also be applied to other existing rule-based model systems, such as livestock densities as a function of past grassland performance (Heinke et al., 2023) or whether to plant cover crops in the off-season (Porwollik et al., 2022).

Figure 7 Recreated figure after Minoli et al. (2022a) (Fig. 1) showing the difference in simulated sowing (a) and maturing (b) between no adaptation and timely adaptation for a climate period 2080–2099 in an SSP460 scenario using ISIMIP3b data (Lange et al., 2024).

3.3 Enhancing classical modelling with LLMs: LLM fertilization

3.3.1 Modelling approach

In recent years, there has been an increasing number of modelling approaches using LLMs to emulate agent behaviour in various use cases, spanning from modelling mobility choices to agents' behaviour in online forums (Gao et al., 2024). This strong synergy with ABM stems from the fact that LLMs are inherently trained to model human language, reasoning, and decision-making patterns (Gao et al., 2024). As such, they are well-suited to serve as proxies for heterogeneous agents, whether individuals, households, or institutions – by generating context-sensitive decisions, goals, or narratives based on inputs from their environment. This capacity makes LLMs particularly compatible with the core idea of ABMs: Simulating the interactions and adaptive behaviour of autonomous entities in a shared environment. However, the integration of LLMs is not limited to ABMs. Their ability to translate between qualitative knowledge and formal rules makes them suitable for enhancing RBMs, for example, by extracting management logic or institutional rules from text sources. Yet, it is in agent-based environments where the conversational and decision-oriented nature of LLMs most directly reflects the modelled processes, making ABMs the current frontier for LLM integration. In the field of land use and agricultural management system, this approach has been taken up by Zeng et al. (2025) to simulate institutional agency of land use dynamics (Chen and Huang, 2024). Using the copan:LPJmL framework, such an approach can also be used to represent the underlying coevolutionary social-ecological dynamics.

Figure 8 Detailed scheme of the LLM-based fertilization approach highlighted in Fig. 1 representing the feedback mechanisms between the taxons ENV and MET. The LLM gets a prompt with the context of the application, information about location and the cultivated crops, as well as ENV output on crop-specific fertilizer applications and corresponding crop yields. This information helps the LLM to decide whether to increase, maintain, or decrease fertilizer levels for the next simulation year.

3.3.2 Model design

As proof of concept for being able to enhance WEMs with LLM agents, we have developed a simple model for nitrogen fertilizer application based on copan:LPJmL (Breier et al., 2025a), whose approach is illustrated in Fig. 8. The basis is similar to that of InSEEDS (Sect. 3.1), in which one farming agent is initialized per grid cell to make decisions about local farming practices based on LPJmL (ENV) observations. However, except for the interface between observations and fertilizer application located in the MET taxon, the farmer or decision-making process has been completely outsourced to the LLM. This way CUL processes are not explicitly represented, neither through modelled interactions between farmers, nor through predefined decision rules based on social norms or beliefs. For simplicity, we have therefore decided to omit the CUL taxon in Fig. 8, even though CUL processes might be part of the LLM reasoning. At the beginning of each simulation year, the farming agent is given a prompt like in Fig. 8 (full prompt available at https://github.com/jnnsbrr/landmanager, last access: 20 May 2026) including ENV observations of the farmer and the request to make decisions based on this knowledge. In the fertilization example described here, the initialized LLM-based farming agents know their geographical position, the crops (CFTs) they grow, the share of land they cultivate, the amount of nitrogen fertilizer applied in each of the last 10 years, and the resulting crop yield for the corresponding years. Based on this knowledge, the LLM-farmers decide on the amount of nitrogen fertilizer they want to apply to each of their crops in the next year, to “increase the crop yield by increasing the application of nitrogen fertilizer as long as it is reasonable” (full prompt in Fig. S2). Moreover, the LLM-farmers are asked to provide their reasoning for the decision taken.

3.3.3 Example simulation results

Results of this model for Togo are depicted in Fig. 9. The map (a) shows that the Nitrogen fertilization level varies strongly from cell to cell and thus proves that the implemented LLM-farmers adopt the Nitrogen fertilization level differently depending on their local needs. After the coupling in 2024, the Nitrogen fertilization levels (b) of all three displayed crops are strongly increased by the LLM-farmer with respective higher harvests (c), with the LLM-farmer reasoning “Increased nitrogen for rainfed rice, maize, and tropical cereals due to low historical application and potential yield gains” (full prompt in Fig. S2). After that, the LLM-agents are only making smaller adjustments to the N fertilization levels, reacting to declines in the harvest. While the maize harvest seems to be stable over the simulated time, rice and tropical cereals show more fluctuating harvests. Thus, the LLM Agent in this cell holds the Nitrogen fertilization level stable for maize, while it adjusts its application to the other two crops. This shows that the LLM-farmer can adapt to changes in the conditions without taking unreasonable decisions.

While this only constitutes a demonstration case, it illustrates the potential of integrating LLM-based agents with copan:LPJmL to introduce more responsive and context-sensitive management decisions. This may offer a more flexible alternative to static assumptions, such as fixed fertilizer levels – in traditional model configurations.

Figure 9 Results of the LLM-based farmer model for Togo in 2050. On the left (a), accumulated nitrogen fertilizer levels between 2024 and 2050 compared to an offline LPJmL run are displayed. On the right, the Nitrogen fertilization (b) and harvest of three crops for one cell ((c), marked as red in (a)) are displayed over time.

4 Discussion

A central aim of copan:LPJmL is to provide a platform for connecting modelling paradigms, research domains, and communities (Sect. 3). In particular, we seek to enable the integration of process-rich, dynamic Earth system model components with models of social dynamics, supporting use cases ranging from SES science to IAM applications. Previous studies have highlighted key limitations in many agent-based and optimization models, which often lack either the integration of detailed Earth system dynamics or the representation of fundamental social systems and their underlying processes (Calvin and Bond-Lamberty, 2018; Krawczyk and Braun, 2025). Conversely, ESMs and DGVMs frequently rely on static or oversimplified representations of human behaviour and decision-making (Sect. 1), despite their otherwise detailed process-based structures. The copan:LPJmL framework addresses these gaps by providing a flexible and extensible WEM framework that supports the realisation of hybrid approaches, unifying natural and social systems science in a synergistic way (Sect. 3). It allows, for instance, the coupling of agent-based decision-making, rule-based logic, or complex dynamical systems with the biophysical processes of LPJmL. The integrated architecture enables the exploration of social-ecological feedbacks and coevolutionary mechanisms across multiple spatial and temporal scales. The current implementations operate based on the LPJmL grid at 0.5° spatial resolution, where grid cells represent aggregated socio-ecological systems rather than individual land holdings. Depending on the research question, this setup can support both aggregated and more heterogeneous representations of social, economic, and institutional processes within and across cells. In particular, copan:LPJmL is well-suited for research questions that require explicit representation of feedbacks between environmental change and human decision-making, such as agricultural adaptation, land-use transitions, policy interventions, or the dispersal rates of management practices. Beyond the specific implementations presented here, the framework enables the representation of a wide range of social and decision-making processes. At the individual level, behavioural decision models can be implemented using agent-based approaches that draw on different theoretical perspectives, ranging from utility-based or economically rational decision-making to bounded rationality and psychologically grounded frameworks such as the Theory of Planned Behaviour, Value–Belief–Norm theory, or social identity approaches (Ajzen, 1985; Stern et al., 1999; Tajfel and Turner, 2004). At higher organisational levels, entities such as groups or social systems can represent collective actors including governments, institutions, markets, or supply chains, enabling the exploration of governance dynamics, policy interventions, and economic interactions. The examples presented in this paper illustrate three different paradigms of decision representation within this framework: behavioural agent-based decision-making by InSEEDS (Sect. 3.1; Schwarz et al., 2025), rule-based management logic using Crop Calendar (Sect. 3.2), and LLM-based decision emulation (Sect. 3.3). Beyond the examples presented here, the framework supports a wide range of additional modelling approaches and combinations thereof. For example, combinations are possible in which InSEEDS farmer agents (example 1) uses (parts of) the Crop Calendar (example 2). The possibilities within the MET and CUL taxon are manifold and include individual decision-making, social learning, institutional rule systems, market interactions, and policy interventions, depending on the modelling paradigm implemented (Donges et al., 2020). The copan:LPJmL framework builds upon copan:CORE and its modular and open structure that has now been enhanced by the LPJmL ENV integration – all without additionally coupling LPJmL within the model code itself. This lowers the entry barrier and fosters interoperability for modellers from diverse fields enabling researchers to incorporate customised decision rules, agent interactions, additional entities such as governance agents or cooperations, and feedback mechanisms, without requiring modification of the LPJmL model. This is also the main advantage compared to many pre-existing coupler libraries (e.g., Hanke et al., 2016; Hutton et al., 2020; Müller et al., 2024). Both the LPJmL coupler library and the Python interface pycoupler (Sect. 2.3) were purpose-built to couple LPJmL with the copan:CORE framework, which is the basis of the integrated copan:LPJmL framework and supports the implementation of numerous projects and ideas, some of which are illustrated in Sect. 3. This approach eliminates the need to integrate libraries that may require advanced technical know-how – such as BMI (Hutton et al., 2020) – for model coupling. At the same time, copan:LPJmL follows the FAIR principles for research software in providing a findable, accessible, interoperable, and reusable modelling software (Barker et al., 2022), with extensive documentation and tutorials available at https://copanlpjml.pik-potsdam.de (last access: 20 May 2026). As with all integrated modelling frameworks, the use of copan:LPJmL involves modelling trade-offs that reflect both computational constraints and the complexity of coupled human–Earth systems. Currently, the coupling between ENV and MET/CUL is only possible on an annual basis, constrained by the LPJmL coupler library and pycoupler (Sect. 2.3). As with all dynamically coupled modelling frameworks, the development of any of the coupled components requires testing and vetting of the coupled system and eventually co-development. Simulated decision-making in MET/CUL does not only depend on plausible decision-making mechanisms, but also on plausible and quantitatively accurate simulated responses in ENV and vice versa. The interpretation of simulation results therefore requires considering both, the behavioural assumptions of the social model and the biophysical responses of the Earth system component. This complexity often results in the continued use of well-tested legacy model versions in coupled systems (e.g.,  Müller et al., 2016). Required testing could be facilitated by a model validation tool chain to allow the harmonization and integration of data sets from various sources such as FAOSTAT (FAO, 2025) for comparing these reference data with simulated data from the coupled system and stand-alone components (e.g. LPJmL) and at a later stage for calibrating the parametrizations of model components. As for now, the functionality of copan:LPJmL and each copan:LPJmL-based model presented here (Sect. 3) is backed up by unit and integrity tests to verify their functional and internal validity. With copan:LPJmL, we intend to provide a modelling framework to address research questions around the complex dynamics of the Anthropocene and its coevolution of human and natural systems. While we have demonstrated several types of models based on this framework (Sect. 3), we expect that more features, revisions and extensions will be necessary for future models built on this framework. The open-source basis of all model components should facilitate necessary changes (Schaphoff et al., 2025; Breier and von Bloh, 2025; Breier et al., 2025b, d). Such extensions can build on the wide range of coupling interfaces and model variables provided by LPJmL and copan:CORE, including the LPJmL input and output categories summarised in Tables 2 and 1, as well as the generic entity types and process taxa of copan:CORE. This enables the implementation of additional entities, processes, and interaction structures within coupled social–ecological systems. At the same time, future developments remain constrained by the process representations and temporal coupling structure of LPJmL, computational limitations, and the need to balance model complexity with tractability and interpretability.

5 Summary and Outlook

This paper introduces copan:LPJmL, a new modelling framework designed to build World-Earth models with a process-rich Dynamic Global Vegetation Model (LPJmL) and a flexible and modular core providing the structures and functionalities to represent various kinds of socio-cultural and socio-metabolic structures and processes. Models built on this framework can represent social and biophysical dynamics in a consistent and coevolutionary manner. With minimal overhead and a lightweight Python interface, copan:LPJmL enables the coupling of LPJmL to diverse types of decision logics – from top-down rule-based models to agent-based bottom-up dynamics – without the need for modifying the LPJmL model itself. By integrating LPJmL as the single component of the ENV taxon into the copan:CORE framework and hierarchy, the framework supports easy access to LPJmL outputs and enables dynamic adjustments to inputs via flexible coupling mechanisms. The three examples presented and discussed in this paper illustrate the breadth of modelling approaches that copan:LPJmL can accommodate: from the top-down, vectorized Crop Calendar, to the bottom-up, agent-based InSEEDS, and towards novel, experimental LLM-based setups. These diverse implementations underscore the framework’s adaptability to a wide range of research questions related to land-use dynamics, adaptation, and the coevolution of human and natural systems. In particular, copan:LPJmL enables the exploration of social–ecological feedbacks in which decision-making processes interact with biophysical dynamics represented by LPJmL. Future work could build on this setup to address gaps in agricultural management data for future projections, support research on planetary boundaries, or explore endogenous policy interventions, including LLM-driven decision processes. Copan:LPJmL provides a flexible foundation for these and many related applications. By adhering to FAIR principles and providing extensive documentation, copan:LPJmL invites collaboration across research domains and communities. It lowers technical barriers for incorporating social dynamics into process-based Earth system modelling and creates a space for new perspectives on topics such as food security, land-use resilience, and regenerative transformations. Ultimately, the framework aims to support the growing need for integrated tools that enable better understanding – and shaping – of coupled human–Earth dynamics in the Anthropocene.

Appendix A: Configuration of LPJmL

Listing A1 Excerpt of the LPJmL base configuration file lpjml_config.cjson with coupled model name (coupled_model), host (coupled_host), and port (coupled_port), start year of coupling (start_coupling) as well as input and outputs to be coupled.

Listing A2 Configuration of a coupled simulation with LPJmL via the LPJmLConfig module of pycoupler. A base configuration is read in as a LPJmLCoupler object and changed for a coupled simulation, including a regridding to simulate the Netherlands only.

Listing A3 Execution of a coupled simulation with LPJmL via the LPJmLCoupler module and run function of pycoupler that is based on the coupler extension (Sect. 2.3). inputs and outputs are objects of class LPJmLData and can be accessed and edited following Hoyer and Hamman (2017); Breier and von Bloh (2025).

Appendix B: Additional figures

Figure B1 Additional crop calendar variables: (a) Global temperature and (b) precipitation change from 2025 to 2090 in the SSP460 scenario using ISIMIP3b (Lange et al., 2023). Harvest rules (c, d, e, f) following Minoli et al. (2019) for both CFTs, temperate cereals and maize for 2025 and 2090. Harvest reason (g, h, i, j) also follows Minoli et al. (2019) with a similar order.