CarboKitten

Modeling Carbonate Platforms in Julia

CarboKitten is a reimplementation of Peter Burgess' CarboCAT, a model for generating carbonate platform stratigraphies. CarboKitten is a three-dimensional model, having two spatial dimensions and one for stored stediment.

Features:

• Cellular Automata to regulate facies type
• Advection-diffusion based sediment transport
• Designed with performance in mind
• Written with Open Science practices in mind

CarboKitten should be easy to get into and extend. All our code is extensively documented.

CarboKitten is written in Julia for performance and extensibility.

Running

CarboKitten requires Julia ≥ 1.10. Please follow the download and install instructions at the Julia homepage if you've never used Julia before.

It is advised to run CarboKitten in a dedicated environment under version control. This way, your model runs can be made fully reproducible. Create a directory for you project:

bash mkdir MyCarboKittenProject cd MyCarboKittenProject git init julia

Start Julia, get into Pkg mode by pressing ] and generate a new project file:

juliarepl (@v1.11) pkg> activate . (MyCarboKittenProject) pkg> add CarboKitten

You can run the example model as follows:

julia using CarboKitten CarboKitten.init() # enables progress logging in this session run_model(Model{ALCAP}, ALCAP.Example.INPUT, "example.h5")

If you wish to visualize the generated output, you'll need to install GLMakie first (in package mode):

juliarepl (MyCarboKittenProject) pkg> add GLMakie

Depending on your system, this may take a few minutes to build. After that, you should be able to run the following:

julia using GLMakie using CarboKitten.Visualization summary_plot("example.h5")

This should show a plot very similar to the one above. Don't worry if it takes a while to render. Subsequent runs in the same REPL should be a lot faster!

For more information on running CarboKitten, please read our extensive documentation, including the full tutorial.

Development

[!NOTE] The following instructions are only relevant if you want to develop on CarboKitten itself.

Start the Julia REPL, and get into Pkg mode by pressing ]. You may activate the package environment using activate . and then install the dependencies using instantiate. These steps only need to be run once.

julia pkg> activate . pkg> instantiate

If you want to start a REPL with the correct environment already activated, use the --project=. flag. Use the -t flag to enable processing in multiple threads.

shell julia --project=. -t 4

Examples

You'll get the best experience by running examples from the Julia REPL. There are however also some example scripts that should work stand-alone.

shell julia --project=workenv examples/ca-with-prod.jl This command will write the output in the HDF5 format into the data folder. You can check that output is written there after executing this command.

However, it is more efficient to run them from the REPL. Either run,

shell julia --project=workenv

or start the REPL from VS Code. In the REPL you can run

julia include("examples/ca-with-prod.jl")

After that, you may edit an example and rerun.

Project layout

. ├── data # data files ├── docs # documentation │   ├── make.jl # docs build script │   ├── Manifest.toml # │   ├── Project.toml # dependencies for building docs │   └── src # markdown source for docs ├── entangled.toml # entangled config ├── examples # example scripts ├── ext # visualization extension ├── Makefile # command-line short hands ├── Manifest.toml # ├── Project.toml # project dependencies ├── pyproject.toml # dependencies for running Entangled ├── README.md # ├── src # tangled library source └── test # unit tests

Global dependencies

CarboKitten has some dependencies that are only needed for developing and running examples, but not for using the library on its own. Those are specified in the workenv package. So make sure workenv is activated (Pkg.activate("./workenv")) or

julia pkg> activate workenv pkg> instantiate

We have experimented with using DaemonMode.jl to run Julia scripts from the command line, but found too many issues with unreproducible errors. So for the moment DaemonMode is not used.

Entangled

While developing, you'll need to run the Entangled watch daemon to keep documentation in Markdown and Julia code synchronized. You may install Entangled using pip install entangled-cli, or use the provided Poetry environment in pyproject.toml.

The first time running, from the project root folder:

shell poetry install

Then,

shell poetry run entangled watch

To generate the more expensive figures (actually resulting from simulation etc.), you may run,

shell poetry run brei figures

Documentation

To generate the documentation, run julia.

pkg> activate docs pkg> instantiate julia> include("docs/make.jl")

The example figures are generated seperately (see previous section), and are included in version control.

The most efficient way to serve this documentation and have it update upon changes, is to run LiveServer from the Julia REPL or

shell julia --project=docs -e 'using LiveServer; servedocs()'

The "Documenter could not auto-detect the building environment Skipping deployment." warning is expected; local changes should not trigger the building of new GitHub pages.

Citations

Bibliography is generated from citations in docs/src/ref.bib using DocumenterCitations.jl. Citing a paper from there is done like [Bosscher1992](@cite).

References

Code in this repository is based on

• Burgess, P. M. (2013). CarboCAT: A cellular automata model of heterogeneous carbonate strata. Computers & geosciences, 53, 129-140.
• Bosscher, H., & Schlager, W. (1992). Computer simulation of reef growth. Sedimentology, 39(3), 503-512.

Authors

Lead engineer: Johan Hidding The Netherlands eScience Center email: j.hidding [at] esciencecenter.nl Web page: www.esciencecenter.nl/team/johan-hidding-msc/ ORCID: 0000-0002-7550-1796

Original author: Peter Burgess University of Liverpool Web page: www.liverpool.ac.uk/environmental-sciences/staff/peter-burgess

Project lead: Emilia Jarochowska Utrecht University email: e.b.jarochowska [at] uu.nl Web page: www.uu.nl/staff/EBJarochowska ORCID: 0000-0001-8937-9405

Other team members:

Niklas Hohmann Utrecht University email: n.h.hohmann [at] uu.nl Web page: www.uu.nl/staff/NHohmann ORCID: 0000-0003-1559-1838

Xianyi Liu Utrecht University email: x.liu6 [at] uu.nl Web page: www.uu.nl/staff/XLiu6 ORCID:

Hanno Spreeuw The Netherlands eScience Center email: h.spreeuw [at] esciencecenter.nl Web page: www.esciencecenter.nl/team/dr-hanno-spreeuw/ ORCID: 0000-0002-5057-0322

David De Vleeschouwer Westfälische Wilhelms-Universität Münster Web page: www.uni-muenster.de/GeoPalaeontologie/erdsystemforschung/staff/DeVleeschouwer ORCID: 0000-0002-3323-807X

Copyright

Copyright 2023-2024 The Netherlands eScience Center and Utrecht University

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Funding information

Funded by the European Union (ERC, MindTheGap, StG project no 101041077). Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or the European Research Council. Neither the European Union nor the granting authority can be held responsible for them.