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.
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:
mkdir MyCarboKittenProject
cd MyCarboKittenProject
git init
juliaStart Julia, get into Pkg mode by pressing ] and generate a new project file:
(@v1.11) pkg> activate .
(MyCarboKittenProject) pkg> add CarboKitten
You can run the example model as follows:
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):
(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:
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.
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.
pkg> activate .
pkg> instantiateIf 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.
julia --project=. -t 4You'll get the best experience by running examples from the Julia REPL. There are however also some example scripts that should work stand-alone.
julia --project=workenv examples/ca-with-prod.jlThis 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,
julia --project=workenvor start the REPL from VS Code. In the REPL you can run
include("examples/ca-with-prod.jl")After that, you may edit an example and rerun.
.
├── 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
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
pkg> activate workenv
pkg> instantiateWe 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.
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:
poetry installThen,
poetry run entangled watchTo generate the more expensive figures (actually resulting from simulation etc.), you may run,
poetry run brei figuresTo 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
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.
Bibliography is generated from citations in docs/src/ref.bib using DocumenterCitations.jl. Citing a paper from there is done like [Bosscher1992](@cite).
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.
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 2023-2024 The Netherlands eScience Center and Utrecht University
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/.
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.