Since the model describes the accumulation of sediment under a range of variable conditions, a short discussion of different measures in the vertical column is in order.

Subsidence rate

Quantified as a rate σ in units of m Myr⁻¹. The growth of sediment is only sustainable in scenarios where there is a steady subsidence. In our models we use a default value of 50 m Myr⁻¹ (or 0.5 mm kyr⁻¹). This parameter can be set by the users.

The general form of our production model follows that of . This model finds the sediment accumulation curve by integrating an ODE that outside of the model parameters only depends on the initial topography. 2∂η∂t=P(η), where P is the sediment production in m Myr⁻¹, 3P(w)=gmtanhI0Ike-kwifw≥00ifw<0, where I0 is the insolation in units of energy flux, Ik is the saturation intensity and should be provided in the same units as I0, k the extinction coefficient in m⁻¹ and gm the maximum growth rate in m Myr⁻¹.

This model encapsulates both the exponential extinction of sun light as water depth increases, and the idea that the growth of organisms interpolates between no growth at great depth and saturated growth in shallow waters (i.e. solar input is not the limiting factor at those depths).

Here we parametrize P as a function of w for w>0. Note that ∇w=-∇η, but otherwise we will use w and η wherever one or the other is more convenient.

Following , we extend the BS92 model by introducing multiple facies that each have their own growth characteristics (except for insolation I0, which is a global input variable). 4P(w)=∑fPf(w)

In the examples presented here we set default values of factory parameters that corrspond to three biological facies based on sediment produced by three carbonate factories: the euphotic (E), oligophotic (O) and aphotic (A) factories. These default values are shown in Table , and the resulting production curves shown in Fig. .

We also provide the option of specifying pelagic production curves. Here the production is computed as the integral of Eq. () over the entire water column.

Representing spatial heterogeneity resulting from positive and negative biological interactions in a computationally simple model requires meeting the following conditions:

infinite heterogeneity in space and time, i.e. no convergence on stable patterns;

These requirements are met by Celullar Automata (CA), as proposed by , and , without substanial computational costs. For this reason we adopt this modeling approach in CarboKitten, directly reimplementing the automaton described by in his package CarboCAT. Cellular automata are commonly used to generate spatial heterogeneity in forward modeling, with some models serving as discrete approximations of partial differential equations that can generate complex spatial dynamics such as Turing patterns .

The CA emulates the biological succession of species by following a set of simple rules. If conditions are right, a species will multiply and occupy neighbouring territory. However, when there are too many of the same kind, the species will die from over population. For each cell in the grid a centered neighbourhood of 5×5 pixels is considered. We count the number of neighbouring cells of the same species. Then we consider two ranges: the activation range (default 6≤n≤10) and viability range (default 4≤n≤10). If the number of live neighbours is in the viability range, the cell stays alive. If the cell was dead, but the number of live neighbours is in the activation range, the cell becomes alive. The neighborhood size and the rules represent a case of Larger than Life family of two-dimensional cellular automata , but this particular set of rules has been proposed specifically for CarboCAT and, to our knowledge, does not correspond to any documented Larger than Life rules. We examined other sets of rules , but most lead to rapid stabilization of spatial patterns. In Fig.  we illustrate the long-term and short-term behaviour of our default CA rule set.

The initial CA grid is randomized. A dead cell may qualify to become alive for different carbonate factories at the same time. To resolve this priority collision, facies priority for occupying a dead cell is rotated every iteration using a deterministic cyclic shift (fixed round-robin pattern), which ensures that there is no priority given to any facies.

In the default configuration we emulate three species, corresponding to the factory species discussed in the section on carbonate production. The state of the CA determines which carbonate factory is switched on for each cell in the grid.

The 5×5 neighborhood strikes a balance between small-scale heterogeneity and computational cost. A smaller neighborhood would result in finer-grained spatial patterns, whereas a larger one in spatial smoothing and larger, more coherent patches of each facies. However, it would slow the model down. In a real depositional system, different carbonate producer guilds have their own length scales at which they disperse and interact and one-size-fits-all neighborhood is clearly a simplification. The size of the neighborhood is fixed in the current version of CarboKitten, but adjustment of granularity of facies distribution generated by the CA can be achieved by users by changing the grid dimensions and the CA interval.

Our transport model is borrowed from other similar approaches in siliclastic (river bed) modeling see, where it is made plausible that this approach is viable for models that work on long time scales. Because our transport model is novel (at least for modelling carbonate platforms), we discuss the full model in a separate section. Here, we discuss how transport is embedded in the larger model.

We consider all sediment transport to happen in an active layer close to the sea floor. This layer has a certain amount of sediment Cf (in units of m) that travels along a path of steepest descent. We say that this material is entrained. Every time step the active layer is supplied with sediment produced in the production step as well as older sediment through disintegration. After transport a fraction of the entrained sediment is deposited on the sea floor as the transported version of the original (donor) facies in a process that we refer to as lithification, being the process of turning loose sediment into rock. Although in reality sediment might not be mobile for a while before lithification sets in, for the purpose of our model, we chose the term to represent the immobilisation of sediment as a whole, see Fig. .

The actual transport is computed using a finite difference approach that is further discussed in Sect. .

Putting everything together, we evaluate the model as follows each iteration:

Advance the cellular automaton.

Advancing the CA can be configured to happen one-in-n iterations to slow it down. Transporting the sediment can be computed on smaller time steps if required for numeric stability. The complete loop is illustrated in Fig. .

CarboKitten has many input parameters: box geometry, time parameters, a list of facies properties, transport model intrinsics and external conditions such as initial topography, relative sea level and insolation. We have already discussed the facies properties in Sect. , and the transport model is discussed in Sect. . That leaves us the external conditions that should be considered the driving forces of carbonate platform formation.

The initial topography, sea level and insolation can all be entered in three different ways: a given constant, a Julia function or an array exactly matching the box size or number of time steps.

In Sect.  we provide two examples where we use external sources to drive the sea level and insolation curves. A full list of input parameters is available in the Appendix.

CarboKitten generates data in the accessible, binary HDF5 format, thus output can be visualised with most common tools, e.g. imported into R or a Jupyter notebook. Nevertheless, we provide some routines based on Makie for creating cross-sections, chronostratigrahic (Wheeler) diagrams and topographic overviews. Some of the most common plot types have been collected into a summary plot, which is shown in Fig. .

In the critical angle approach developed by , sediment is transported from unstable slopes to the nearest down-slope stable region. Stability is defined separately for different grain sizes. This method is motivated by the empirical relationship between grain composition and maximum slope angle .

The problem with this critical angle-based method of transport is that production across an unstable region is deposited on a small strip, where slopes are below the critical angle. It becomes unclear how to interpret these models from a physics point of view, as results depend heavily on the time-step that is chosen. Contrasting to that, both our transport model and production model (with the exception of the cellular automaton) are discretisations of otherwise continuous processes. This means that, at least assymptotically (i.e. as long as the time step is small enough), our implementation is independent of the chosen time step.

One aspect of critical angle theory that we do use is that we can modulate the disintegration rate rd (and therefore the amount of entrained material) with the magnitude of the slope |∇η|. If we only disintegrate material where the slope is supercritical, the net effect is that sediment is transported from supercritical to stable areas. The difference is that we have a much better control over the physics, and there is no need to convert back and forth between gridded values and a particle representation used in the critical angle approach e.g.. A different approach has been used in the early model CARBPLAT by , which took empirically observed carbonate slopes and defined a slope function that returned slope parameters bounded by the limits of the angle of repose. In the study by an exponential slope function was assumed, although it should be noted that there is literature debate on the distribution of slope shapes of carbonate platforms e.g.,. This modelling approach is agnostic with respect to sediment properties and transport mechanisms and optimises the similarity to observed shapes, allowing the user to choose the parameter that produces the best result. However, it does not allow modelling a mixture of sediment types with different properties and requires an a priori assumption on the expected slope shape. It had not been adapted in subsequent models.

Our transport model is based on the elementary assumption that sediment flux is proportional to the slope of the sea floor. Nevertheless, we are extrapolating this idea to time scales on which it is hard to reason or otherwise measure the parameters to our model. Especially the combination of transport coefficient df, disintegration rate rd and lithification time tl can be pivotal in acquiring a set of physical outcomes, while we have no good way to estimate acceptable ranges of values for them, other than trying them out and see if the results are plausible.

That being said, by considering some artificial scenarios we can gain more insight into the behaviour of our main parameters.

Our implementation of the transport model first computes the gradient of the sea floor (or equivalently the water depth) ∇w using central differences. From this gradient we can compute the advection coefficients in Eq. (), cadv=df∇η+vf(w). The maximum advection coefficient sets the Courant number and determines how many time steps we need to take to solve Eq. (). For an advection equation integrated with the forward Euler method, we need 11|cadv|∞ΔtΔx≤1. This states that we cannot move matter further than a single pixel distance in one iteration, or our computation becomes unstable.

In practice, we compute the transport coefficients and the maximum resulting advective Courant number. Then we integrate the transport equation adaptively, choosing the minimum number of subdivided time steps that keeps the advection stable. Since we computed the transport coefficients in advance, it is relatively cheap to apply multiple iterations of the advection solver, for which we use a first-order upwind scheme.

Now consider our transport model in the context of the larger carbonate platform model. Each time we disintegrate some matter which gets entrained and transported as part of the sediment concentration Cf, after which a fraction is cemented, increasing η. If we consider ∂η/∂t∼∂C/∂t, then part of the transport equation is the diffusion equation ∂η/∂t∼dfCf∇2η. This leaves our implementation vulnerable to instabilities when the global time step is taken too large. For just this diffusion term the CFL limit is 12dfCfΔt(Δx)2≤1.

This means that increasing the resolution of a model by a factor two may need a time step four times smaller for the integration to remain stable. CarboKitten has a diagnostic mode where this condition is checked against, allowing the user to make informed changes to the input parameters. Because the sediment concentration is not known in advance, it is not possible to make this check in advance.

CarboKitten needs to work with different choices for box topology, i.e. how the boundaries of a model box connect to each other. For example, when we simulate a small strip of coastline it is best to have one axis (in this case the x axis) reflect onto itself, while the other axis is periodic, leaving fewer edge effects.

In another case, where we want to simulate an entire island, or even an archipelago, it is more convenient to use fully periodic coordinates. We illustrate these choices in Fig. .

In our models of sediment transport and denudation it is important to remember the sedimentation history for all produced facies for some time into the past. We keep a three-dimensional fixed-size buffer, where two dimensions represent the x and y coordinates of the system, and the third dimension discretizes the amount of deposited material. Each cell in the buffer represents a parcel of sediment, where we store the relative fractions of each contributing facies. The data-structure acts like a stack, working on a First-In-First-Out (FIFO) basis.

We emphasise that this buffer is only used to determine the facies composition of disintegrated sediment. The sediment output of the overall model is written to disk at each iteration for post-analysis. This means that the model output can be much more precise than the depositional resolution of the buffer.

The user can set the size of the buffer as well as the amount of sediment represented by each cell. The depth of the buffer is controlled by an input parameter sediment_buffer_size, while the resolution is set through the depositional_resolution parameter in units of m of sediment.

The rows in the buffer represent a constant amount of sediment. An alternative approach is to have rows that represent time slices. In that case, when we need to disintegrate an amount of sediment, we need to search the buffer back in time until enough sediment is collected. This can be very slow, and it also means that one needs to have the full sedimentation history in memory. A buffer that is discretized on depth however does not have those requirements, at the expense of a small amount of facies mixing.

While the sediment buffer is allocated as a single 4-dimensional array (depth, facies, x, y), it is best to explain its functioning from the perspective of a single cell in our model. We are left with two dimensions: depth (rows) and facies (columns).

We choose to have the head of our sediment stack always be at the first row. When sediment out-grows the buffer, the deepest layers are dropped from memory. The head can contain an incomplete amount of sediment, while all rows below the head are either full or empty. When sediment is pushed to the stack and the head row overflows, all rows are copied down one row and the surplus is assigned to the now empty head row. The inverse happens when removing (popping) material from the stack. This process is illustrated below in Fig. .

The user interfaces CarboKitten by writing a Julia script that defines the relevant model parameters and runs the chosen model. Effectively, very little Julia needs to be known to take an example input and modify parameters. Output is written to HDF5 files for post-processing and visualization.

CarboKitten ships with routines for visualisation and data extraction into CSV files. This makes it easier for novice users to use results from CarboKitten in further processing pipelines that rely on other programming languages. Data extracted includes sediment accumulation curves, age-depth models, water depth, and stratigraphic columns with facies code, allowing to test a wide range of hypotheses. These include, but are not limited to, testing hypotheses on orderedness of strata , preservation orbital forcing , proxy records , or preservation of biotic information such as patterns of origination and extinction, biostratigraphic precision, and evolutionary change .

Since CarboKitten is written in Julia with performance in mind, it should be efficient to run, even on consumer grade hardware, i.e. an average laptop. We are yet to substantiate this claim. Since Julia is a just-in-time compiled language, the first execution of any code in a new session always takes a bit longer than subsequent runs. Measurements presented in this section do not include this initial overhead.

CarboKitten is written entirely using literate programming . This means that the implementation of CarboKitten is written as an integral part of its own documentation, using a system called Entangled . The aim is that interested readers have a direct reference to the code implementing the methods that are explained in the documentation.

Variables external to the model, which modulate the output the most, are the sea level and insolation. The sea level, together with subsidence, result in the relative sea level, which translates into water depth at any given position in the basin. The sea level must be specified as a function of time. It can be a constant, a continuous function or an empirical dataset. Empirical datasets can be read in as text files and need to be interpolated to equidistant intervals corresponding to the time step with which the model is run. The example here uses the sea level curve by , reproduced in the compilation by . The dataset of relative sea level records derived from foraminifer δ18O extracted from this compilation is included in CarboKitten to facilitate simulations of the most typical sea-level scenarios. In this example we start the model at 2 Ma and build the platform until 134.54 ka, i.e. until the end of the record by , using a time step of 200 year (Fig. ).

The relationship between production and insolation can be modified with user-provided parameters. It may be confusing that the extinction coefficient k is, in CarboKitten, a property of the carbonate factory and the facies it deposits and not of the basin or position in it. In reality extinction coefficient varies for different wavelengths of the sunlight spectrum, but the set of its values across the spectrum is constant for a given water body. While different carbonate factories exploit (or ignore, in the case of the aphotic factory) different parts of the light spectrum, the model is agnostic to it and allows users to set k to values that may represent an average across different producers using different wavelengths.

As default, we use insolation of 400 W m⁻², which is approximately equivalent to the 2000 µE m⁻² s⁻¹ used by . This is representative of insolation on the sea surface at midday in the tropics. However, insolation varies with the position of the Earth with respect to the Sun and over geological timescales this variation may affect the patterns of sediment production. Incoming solar radiation can be used as an input vector to modulate production. CarboKitten is agnostic with respect to the source of this information. As an example in Fig. , here we use the daily mean insolation on June solstice, calculated using the astronomical solution by , obtained through the R package palinsol . Here we obtain it for the coming million year (starting in 1950, which is when the astronomical solution starts) at the 25° N latitude and use the total solar irradiance value of 1361 kW m⁻². Variation in solar irradiance is so small that it would hardly manifest itself if linearly propagated to the sea level curve. A universal transfer function describing the relationship between insolation and sea level does not exist. For the purpose of illustrating the functionality of the model, we calculate the sea level as an amplified insolation value. The amplification is chosen arbitrarily as the square of the insolation anomaly, with the anomaly being the deviation from mean irradiation.

The insolation file can be read into a CarboKitten script defining the model to be run. The alternative is calling R directly from Julia using RCall.jl.

We model the transport by waves by setting the velocity vf and shear sf components in Eq. (). In this analysis we forego claims on any level of realism with respect to the true long term effects of wave transport, rather we study the behaviour of the model under an imposed additional velocity component. Our use of the term wave transport should also be understood as such.

Considering the long timescales we are working with, we limit ourselves to a highly simplified model, with the goal of achieving an effect comparable with that of wave-induced transport. Given the timescales for which the model is developed, with time steps of the order of 100 years, a more physical representation of wave-induced transport is not possible. By necessity, the result imitates the time-averaged effect of transport.

Our approach is illustrated with an example of an atoll, starting with a conical topography and periodic boundaries.

Here we try three different velocity profiles: first no onshore component, second a constant vector that does not depend on water depth, and third an attempt at a more realistic scenario.

The following equation is the well known phase velocity of waves as a function of depth from linear wave theory, 13v(w)=λgktanh(kw), where w is the water depth, k the wave number (k=2π/λ), and g is the gravitational acceleration. This velocity is the phase-velocity of surface waves, given the total depth of the water. To evaluate the transport velocity at deeper levels, we multiply the phase velocity with a factor exp⁡(-kw) to account for Stokes drift: 14vf=Afexp⁡(-kw)tanh(kw), where Af is the facies-dependent maximum transport velocity. The k parameter can be tweaked to set the depth at which the maximum transport velocity is attained. We assume most of the sediment transport happens close to the sea floor. This profile is chosen for its assymptotic properties: at high water depth the transport velocity converges to zero, while the decrease in wave velocity towards shallow depths ensures that there is a net influx of material close to the shore. An example of this profile is shown in Fig. .

We model the formation of an atoll for three cases: no wave transport, constant transport directed west-ward (along the x-axis), and a depth dependent velocity profile. The results of this experiment are shown in Fig. . Velocity functions are configured for each facies separately. We found that it was quite easy to create an unstable model by choosing on-shore velocities too high, particularly in the case where the velocity shear is non-zero. Build-up of material due to high on-shore velocity can be compensated by setting a higher facies transport coefficient.

If we assume that both the facies transport coefficient and the wave velocity are some constant times a hypothetical carrying water velocity, it would be fitting to make sure that for each facies the transport coefficient and velocity have a similar proportion. In our experiment we took the values listed in Table . It is very hard to find proper motivation for any of these values, but by changing them we can learn more about the mechanisms and systematic behaviours of the model and by extension possibly learn more about the formation of carbonate platforms and study sensitivities in their observed stratigraphic patterns.