Plankton community modeling is a critical tool for understanding the processes that shape marine ecosystems and their impacts on global biogeochemical cycles. These models can be of variable ecological, physiological, and physical complexity. Many published models are either not publicly available or implemented in static and inflexible code, thus hampering adoption, collaboration, and reproducibility of results. Here we present Phydra, an open-source library for plankton community modeling, and Xarray-simlab-ODE (XSO), a modular framework for efficient, flexible, and reproducible model development based on ordinary differential equations. Both tools are written in Python. Phydra provides pre-built models and model components that can be modified and assembled to develop plankton community models of various levels of ecological complexity. The components can be created, adapted, and modified using standard variable types provided by the XSO framework. XSO is embedded in the Python scientific ecosystem and is integrated with tools for data analysis and visualization. To demonstrate the range of applicability and how Phydra and XSO can be used to develop and execute models, we present three applications: (1) a highly simplified nutrient–phytoplankton (NP) model in a chemostat setting, (2) a nutrient–phytoplankton–zooplankton–detritus (NPZD) model in a zero-dimensional pelagic ocean setting, and (3) a size-structured plankton community model that resolves 50 phytoplankton and 50 zooplankton size classes with functional traits determined by allometric relationships. The applications presented here are available as interactive Jupyter notebooks and can be used by the scientific community to build, modify, and run plankton community models based on differential equations for a diverse range of scientific pursuits.

Scientists have used mathematical models to advance our understanding of marine ecosystems for at least 70 years

Despite this progress, we argue that the technical implementations of plankton community models are often inflexible, complicated, and inaccessible, which obscures valuable research and presents a high barrier of entry for beginners or students. Existing model code is rarely reused beyond the development teams

A collective and dedicated effort in the marine ecosystem modeling community is ongoing to improve on these issues. It has become more common to publish model source code, and there is an ongoing development of open-source frameworks that can make models more approachable, flexible, and reproducible

To efficiently test and answer ecological and biogeochemical questions using plankton community models, we need modeling tools that (1) are easy to use, (2) are open-source, (3) allow flexible and granular control of model structure, and (4) are conducive to scientific collaboration via an open and extensible framework. These motivations led us to develop the novel XSO framework and Phydra library in the programming language Python. The XSO framework offers a set of building blocks for developing computational models based on ordinary differential equations. XSO is used as the basis of the plankton community models contained in the Phydra library. The foundational framework facilitates the modification of model structure, dimensionality, and parameterization. The ultimate goal is to provide usability and flexibility in line with popular Python data analysis and visualization tools, such as Pandas, Xarray, and Matplotlib. The XSO framework depends on functionality from these packages and provides direct interoperability for an integrated modeling environment.

In the next sections, we present the XSO framework and structure of the Phydra library, including the steps of an exemplary model development workflow. We show the utility of the tool set in three exemplary model applications: (1) a basic nutrient–phytoplankton (NP) chemostat model, (2) a nutrient–phytoplankton–zooplankton–detritus (NPZD) model in a slab-ocean physical setting adapted from

Xarray-simlab-ODE (XSO) is a Python framework that allows users to construct and customize models based on ordinary differential equations (ODEs) in a modular fashion. It is a non-opinionated framework; i.e., it does not provide a fixed notion of how a model should be implemented. Instead it attempts to remove the redundant boilerplate code, allowing a user to efficiently construct and work with ODE-based models. XSO was developed as the technical foundation of the Phydra library but is not limited to any particular domain and can be used to create ODE-based models of any type. The typical steps of a model development workflow are presented in Fig.

Schematic of a typical workflow utilizing XSO and Phydra. XSO provides the framework. Phydra is a library of functional components and pre-built model objects that can be used, extended, and modified. A typical workflow would consist of five steps. (1) Choose a pre-existing model, and potentially remove or add components or create a new model using

The XSO framework is an extension of Xarray-simlab

Xarray-simlab has found various applications, for example in landscape evolution

Our objective in developing the XSO framework was to enable users to construct ODE-based models to be readily modified, especially in relation to dimensionality as well as the number of state variables and processes involved. XSO provides an interface for iterative modifications to both more complex and simpler model constructs. The building blocks provided by XSO are as follows.

The system of differential equations is constructed from the fluxes using the labels supplied during model setup. The number of values in a defined dimension is flexible, but they have to match across the model in order for the model to run. When executing the model by calling the

The XSO framework currently provides two solver algorithms: an adaptive step-size solver from the SciPy package

Phydra is a Python package that provides a library of modular plankton community models built using the XSO framework. Phydra establishes conventions and common usage for building models using XSO.

The plankton community models included in the Phydra package are available to the user at multiple hierarchical levels: as a library of pre-built XSO model components, as pre-assembled model objects, and as exemplary model simulations in interactive Jupyter notebooks. These levels are described below.

The open-source and extensible nature of Phydra and XSO enables users to customize and develop processes that accurately describe a particular ecosystem. In a collaborative effort aiming to promote efficient, transparent, and reproducible marine ecosystem modeling, Phydra encourages users to contribute their own components and models to the core library. The Phydra library could potentially offer a comprehensive, well-documented, and peer-reviewed code base for the scientific exploration of plankton community models. Phydra is available via GitHub

To showcase the utility of the XSO framework and Phydra library, we present three plankton community model applications of varying complexity. For each application, we present the mathematical model, the implementation within the XSO framework, and the model results. To highlight the flexible nature of the model implementations, we also show how one aspect of each model can be modified.

For the first application, we consider a simple chemostat model, whose implementation using the XSO framework is presented in full detail. For the presentation of the more complex models, we show only the component structure and highlight additional technical aspects of the implementation. For all use cases, the complete codes, following the full development workflow from model creation to output visualization, are available publicly as interactive Jupyter notebooks in the “notebooks” folder of the Phydra repository

Chemostats are a commonly used experimental setup for studying the growth dynamics of microorganisms under controlled laboratory settings. They are characterized by a constant inflow of the medium containing nutrients and a constant outflow of the culture, both at a fixed rate

Schematic of model application 1: phytoplankton P consuming a single nutrient N in a flow-through chemostat system. The chemostat system is supplied with external medium with nutrient concentration

To showcase the flexibility and simplicity of the XSO framework, we consider two cases: (1) a constant nutrient input and (2) a sinusoidal nutrient input (time-varying

The chemostat model is presented in Fig.

Phytoplankton growth

The model equations are

To meaningfully structure our model within the XSO framework, we separate the model into state variables, forcing, and fluxes. For state variables, we have nutrients (

To explore the basic model dynamics, we choose standard parameter values (Table

Schematic representation of the chemostat model using the XSO framework and included in the Phydra library. Model setup with constant forcing

List of variables and parameters considered for the NP chemostat model. In addition to values and units, we report the variable names to compare with Fig.

In order to run the model with periodic forcing, we simply exchange the forcing component from

Figure

Model outputs for the two chemostat scenarios:

By producing expected results with a very simple model setup, this first application represents a basic proof of concept of our framework and library.

The classic nutrient–phytoplankton–zooplankton–detritus (NPZD) model is embedded in a slab-ocean physical setting (e.g.,

Schematic of model application 2: the nutrient–phytoplankton–zooplankton–detritus (NPZD) slab model. The model structure is adapted from

In the model, phytoplankton growth is driven by temperature, light, and nutrients. Phytoplankton are consumed by zooplankton, which are in turn subject to a higher-order mortality (such as predation by higher trophic levels). Phytoplankton and zooplankton mortality and grazing by-products fuel a detrital pool that is remineralized in the upper ocean. Changes in the depth of the upper mixed layer have effects on all components. Nutrients are exchanged between the upper ocean and deep ocean across the mixed layer boundary. Fractions of phytoplankton, zooplankton, and detritus are lost due to mixing, with detritus additionally sinking out of the mixed layer at a constant rate.

Many NPZD-type models have been published over the years, with a variety of formulations for the functional responses of the ecosystem components.

The model expresses quantities in units of

The model is driven by external forcing describing the depth of the upper mixed layer

The deeper layer supplies nutrients to the upper layer. Fractions of all state variables are lost into the deeper layer due to mixing. The rate of mixing is described by

Dissolved nutrients in the mixed layer (

The growth rate of phytoplankton

The temperature of the upper mixed layer

Nutrient limitation of phytoplankton growth

The term

We use the Smith function to calculate the photosynthetic rate

The light limitation on phytoplankton growth

In order to test various levels of model complexity, we also consider light attenuation according to a three-layer model of the upper mixed layer

Non-grazing mortality of phytoplankton is described by the sum of linear

Zooplankton graze upon phytoplankton and detritus. The grazing function is a sigmoidal (or Holling type 3) grazing response

This formulation describes the total biomass of phytoplankton that is grazed

Grazing on detritus is defined as

Zooplankton food ingestion is not directly converted into biomass. The total biomass grazed (

Similar to phytoplankton mortality, a linear mortality factor

The detritus concentration in the upper layer (

The ecological description of our model system is adapted from the EMPOWER model; however, the technical implementation using the XSO framework is quite different from the procedural R script of

The fluxes and interdependencies between the calculations in this application require a more elaborate component structure. As for the previous model application, we first separate the model into state variables, forcing, and fluxes. State variables include nutrients (N, Eq.

In implementing this model within the XSO framework, we aim to find a balance between component refactoring and structural simplicity. Our goal is to allow every ecologically relevant term to be exchangeable, while making full use of the flexible dimensionality features. This resulted in the structure presented in Fig.

Schematic representation of how the NPZD slab-ocean model is implemented with the XSO framework and included in the Phydra library. To simplify visualization, we show only the XSO components with their labels and links. Each component contains various variables, forcings, or parameters. Solid arrows indicate the flow of fluxes between state variables. Dashed arrows indicate fluxes passed along as group variables. Dashed lines connecting processes indicate variables and forcings referenced in another component via their label.

Parameters considered for the NPZD model applied to four ocean stations.

Parameters considered for the NPZD model applied to the four stations. These are optimized parameters, adapted from

Forcing corresponding to the four locations considered for the NPZD model application. Mixed layer depth (

To highlight one aspect of our implementation, each factor affecting phytoplankton growth is defined by an individual component. The “group to argument” feature of the XSO framework allows such a setup to remain highly modular, since the output of each flux with the appropriate label is utilized in the product of growth-limiting terms. Similarly, the component calculating the mixing coefficient

Following

To highlight another technical aspect, we use the batch dimension feature of the XSO model setup function to evaluate the model for all four stations in unison. This feature allows us to define a new dimension at model setup and to supply a list of values for parameters of that dimension. In our case, this additional dimension defines the four stations via the specific forcing and the parameters

We additionally show a modification of the model:

Model outputs for the four stations are shown in Fig.

Results of the NPZD model (application 2) for locations

The climatological data show a marked seasonal cycle visible with a clear spring phytoplankton bloom for stations BIOTRANS and India, as expected, given their location in the temperate North Atlantic. Stations Papa and KERFIX show less pronounced cycles but still some seasonal variation, with generally higher phytoplankton and zooplankton concentrations in summer (in their respective hemisphere). Zooplankton and detritus dynamics clearly follow phytoplankton concentrations, as expected. In general, the model output agrees relatively well with our verification data, with the optimized parameters from

These results show that our framework can accurately recreate the results of published marine ecosystem modeling studies within a flexible and modular environment, which allows further experimentation and testing of different model structures.

Our third model application is a size-structured plankton community model in an idealized physical setting, similar to a chemostat. The presented model is an adaptation of the ASTroCAT model, developed by Neil Banas

Banas considered model dynamics under variable forcing or with stochastic grazing parameters. Here, we focus on the basic parameter setup under constant forcing. While trophic interactions between phytoplankton and zooplankton size classes are highly resolved, other ecological processes are neglected (e.g., there are no detrital or regeneration pathways).

This model lends itself well to highlighting the flexibility of the XSO framework. A state variable defined within a component can be defined with a dimension label so that it can represent an array of state variables of flexible size, as long as dimension labels match across components in the same model. The size of the state variable array depends on the number of values supplied at model setup. The built-in vectorization allows the model to compute correctly and efficiently, even with large numbers of state variables. We showcase this feature by running the model with 2 to 50 size classes and comparing bulk phytoplankton biomass between runs. The only modification necessary is varying the number of values supplied at model setup.

The model expresses quantities in units of

The model describes size-structured communities of phytoplankton and zooplankton, whose sizes are expressed in terms of equivalent spherical diameter (ESD). Following

Schematic of the size-resolved

Model nutrient N (

Each phytoplankton size class

Phytoplankton loss due to natural mortality and excretion is described with the factor

The grazing of the zooplankton size class

Prey preference is assumed to vary with phytoplankton size

Zooplankton growth is calculated as the product between total biomass grazed (

Zooplankton experience quadratic losses according to the parameter

Parameters were adapted from

Schematic representation of how model application 3 is implemented in the XSO framework and included in the Phydra library. For simplicity, only the XSO components with corresponding labels and links are shown. Each component consists of a number of variables, forcing, or parameters. Solid arrows indicate the fluxes between state variables. Dashed arrows indicate fluxes passed along as group variables. Dashed lines connecting processes indicate variables and forcing passed along via their label. Arrows with multiple lines indicate values with dimensions that are passed along.

Parameters and allometric functions used for the size-based NPZ model.

Parameters adapted from

We separate the model into state variables, forcing, and fluxes. State variables are nutrients (

The original ASTroCAT model was implemented with an interactive graphical user interface showing animations of model outputs. Our implementation in the XSO framework lacks this but provides some technical updates, with the major differences being the modular component structure and the use of vectorization (instead of for-loops) to define functions computing the fluxes acting on arrays of size classes.

Running the model with 40 size classes of phytoplankton and zooplankton recreates the dynamics originally presented by

To investigate the effect of the number of resolved size classes on the model output, we conduct comparative model runs varying the number of phytoplankton and zooplankton between 2 and 50. Figure

Nutrient concentration and plankton biomass under steady nutrient forcing obtained with model runs resolving 40 phytoplankton and zooplankton size classes. Size classes are log-spaced in the range of 1 to 20

Comparative runs of our implementation of the ASTroCAT model with varying numbers of size classes of phytoplankton and zooplankton.

We argue that codes of plankton community models are often built to be run, but not to be shared, reused, and modified, which is in part an issue related to the programming languages and tools used to create them. This is in contrast to current computational tools for data analysis (for example, as developed by the Python or R programming communities) that focus on modularity, usability, and clear documentation in an open-source, collaborative context.

The XSO framework in its current version allows building models quickly and dynamically from components and provides a user interface to set up and run a model that is stored as a fully documented Xarray dataset. The Phydra library provides a set of components, models, and example applications that showcase the usability of the framework and provide a common library for marine ecosystem modeling applications. The first release of the Phydra library, presented here, contains implementations of two published plankton ecosystem models, the EMPOWER model by

There has been an increasing move towards developing and using frameworks that systematize or simplify at least one specific aspect of model development (e.g., FABM for model coupling;

Our goal in developing the framework was to allow users to build models without restricting the level of complexity, in particular in relation to the dimensionality, number of state variables, and model processes. This was implemented in the framework by providing variable types, which directly correspond to the basic mathematical components of models based on ordinary differential equations (e.g., state variables, parameters, forcing, and partial equations). Every aspect of the model needs to be defined at the level of variable types. Model components can be flexibly constructed from the provided set of variable types and wrap a logical component of the model as users see fit. State variables, forcing, and parameters need to be initialized in one component but can be referenced across the model. The system of differential equations is constructed from the fluxes contained in the model components via the supplied labels at model setup. These design choices make the effort required to construct models proportional to the desired model complexity, and components can be easily modified to more complex formulations. In order to provide a template for utilizing this flexible framework, we present fully implemented models in the Phydra library. We hope that this will foster experimentation and intercomparison of model performance at different levels of complexity.

In addition to flexible model construction, we wanted to provide an interface for iterative modification and prototyping. An ecosystem model tracks chemical compounds and ecosystem components via state variables. These state variables can define completely different components of a model or represent functional groups. In the third model application, we presented such a case by defining an array of variables for phytoplankton and zooplankton via size-based allometric functions. This flexible dimensionality of model components was designed with the current issues in marine ecosystem modeling in mind. The effects of different levels of complexity in the number and definition of phytoplankton functional types (PFTs), for example, is not routinely tested in marine ecosystem models

The choice of programming language has an important effect on the resulting framework. In contrast to available tools that allow building models based on differential equations from a set of customizable building blocks through a graphical interface (e.g., Stella, PowerSim, Ecopath) or other frameworks that utilize a custom scripting language (e.g., via YAML files), the Phydra and XSO front end and back end are fully implemented in a single programming language: Python. This might require a higher initial effort for users unfamiliar with Python, but we argue that the effort is worth it given the wealth of functionality provided by the Python scientific ecosystem and the support of the large community of programmers and developers. The XSO model development workflow is similar to writing standard Python codes, with the added benefit of having at hand a set of modular Python objects and attributes that automatically handle model inputs and outputs and that allow computationally constructing and running models.

Since the XSO framework is fully implemented in Python, functional model components have to follow a basic structure but are otherwise flexible. The functions defining forcings and fluxes within components in XSO are not restrictive in their Python syntax and can make use of external Python packages, as long as the value that is finally supplied at model runtime is compatible with the chosen solver back end. Since XSO itself is a wrapper of Xarray-simlab without hiding its underlying functionality, XSO further expands the possibilities for custom applications and further development of the Xarray-simlab framework. The relative complexity of the back-end framework should not dissuade users less interested in technical customization, as the Phydra library provides fully functional pre-configured components and model objects that provide a blueprint for the development of marine ecosystem models using XSO.

The software presented here was specifically designed to support collaborative model development. Scientists working with computational models do not always build the models themselves. Often, scientists use existing models and focus the work on parameterization and analysis of results obtained with model applications in specific locations. This type of use is specifically supported in our software because we equipped the Phydra library with pre-built model objects and components. A user can start working with models without detailed knowledge of the underlying framework and learn the basic workflow before progressing to building custom models using the XSO framework. Additionally, more advanced users can easily share custom components or model objects via the respective Python objects. This particular feature of design also makes our software suitable for teaching.

The presented software packages are in the early stages of development and as such have limited functionality. This first version of the XSO framework supports mathematical models based on ordinary differential equations. In the first release, the framework functionality and library contents are focused on zero-dimensional physical settings for marine plankton models. The first version of XSO implements two numerical solvers. These are (1) a simple step-wise solver and (2) an adaptive step-size solver optimized for solving a system of ODEs (

XSO is available via the package installer for Python (pip). Detailed instructions about installation and resolution of dependencies can be found in the online documentation

The Xarray-simlab package that provides the basis for the XSO framework is a relatively young project but has found robust usage in, for example, the Fastscape package

Since the XSO framework is embedded in the larger Python scientific ecosystem, there are many possibilities to provide advanced functionality on top of the basic model development workflow currently supported. Amongst our foremost development goals are developing the solving back end further to support larger models and possibly multidimensional physical settings. The solver back end could be adapted to use highly optimized solvers, such as the Mobius framework

The Phydra library of components and model objects could be expanded beyond the three applications presented here and would allow easy comparability and reproducibility of specific model applications, as demonstrated here.

We presented two new Python packages that provide a flexible tool set for plankton community models based on differential equations. Phydra is a library of pre-built models and their individual building blocks (i.e., components), which can be combined or modified to create custom configurations. The XSO package, which is the technical foundation of Phydra, provides a user interface and modeling framework for building and solving computational models based on differential equations. The XSO framework grants users granular control over state variables, parameters, forcing, and mathematical functions, while allowing each model component to remain interchangeable. Additionally, Phydra utilizes the Xarray dataset format for structuring model input and output, including metadata, allowing for easy storage, sharing, and analysis of data. The Phydra library in the initial release contains three model applications of variable ecosystem complexity, from a simple chemostat model to a size-resolved plankton model. These three applications are contained in the Phydra library via their respective model components and as fully assembled model objects. Additionally, all scripts used to create the presented results are available in fully documented Jupyter notebooks.

The Phydra library can be a reference and learning resource for scientists interested in marine ecosystem modeling, a starting point for scientific exploration, and a valuable tool for teaching. The model development effort is proportional to the desired complexity of the model application, so users can quickly implement simple models. Further developing such a fully integrated environment for marine ecosystem modeling will require a diverse community of users and developers. We believe the programming language Python provides strong enough functionalities and a wide enough user base. Hence, Phydra and XSO can contribute to the ongoing efforts of developing more robust, transparent, and reproducible models, moving away from static and inflexible codes to a model development process that is inherently collaborative.

Xarray-simlab-ODE (XSO) and Phydra are fully open-source and available under a BSD-3 license on GitHub. The XSO framework is available via

BP conceived of and wrote the Phydra and XSO Python packages. BP, EAT, ADB, and AM conceived of the paper structure and model applications presented. BP, EAT, ADB, and AM wrote the paper.

The contact author has declared that none of the authors has any competing interests.

Publisher's note: Copernicus Publications remains neutral with regard to jurisdictional claims made in the text, published maps, institutional affiliations, or any other geographical representation in this paper. While Copernicus Publications makes every effort to include appropriate place names, the final responsibility lies with the authors.

We want to thank the open-source developers that made this work possible. In particular, we want to thank Benoît Bovy for advice on some aspects of the code structure and for developing Xarray-simlab. Esteban Acevedo-Trejos acknowledges the support of the German Research Foundation (DFG) via grants AC 331/1-1 and 268236062, as part of the priority program “DynaTrait” (SPP 1704) and the collaborative research center “Earth-evolution at the dry limit” (CRC-1211), respectively.

The publication of this article was funded by the Open Access Fund of the Leibniz Association.

This paper was edited by Andrew Yool and reviewed by two anonymous referees.