Getting Started
DAR1 is a tool for designing and running experiments simulating the marine microbiome within a single cube of water. The biogeochemical forcing is powered by the MIT Darwin Model, and DAR1 provides a Julia interface to build, configure, and run experiments with a simple, streamlined workflow.
DAR1 Model Configuration: The DAR1 system models a single, well mixed parcel of water. The standard configuration consists of the DARWIN ecosystem-biogeochemical model, with free gas exchange with the atmosphere. Horizontal and other vertical fluxes are set to zero. These conditions can be modified by the user.
Basic Structure
DAR1 is composed of three main parts: the MITgcm Darwin code, a configuration made for DAR1, and the julia interface to modify the configuration and run the model.
- DAR1 - Julia interface for organizing experiments and setting up parameters for model runs
MITgcm_path
variable needs to point to darwin3
- darwin3 - MITgcm source code set up to include all things Darwin
dar_one_config
- folder for the base configuration files for DAR1, which lives in the darwin3/verification/ folder. (DAR1_config github)
Experiments are designed and run in a Julia file using the DAR1 Julia interface. This will create a unique run folder nested underneath the MITgcm darwin code and the daroneconfig folder. You will never have to look at the fortran of MITgcm Darwin or at the configuration files! However, output of the experiment is saved underneath that unique run folder that is created in darwin3/verification/dar_one_config/run
.
Installation
DAR1 can be run in one of two ways.
- In a docker container using the DAR1_docker image, where all dependencies are handled for you
- On your local machine, where you have to set up the environment, download dependencies, etc
- this is more time consuming, and I strongly recommend using the docker image
- instructions for local setup are below
Setting up with docker
(1) Download and install docker desktop.
- Run the docker application, which will start up the docker "daemon"
- The docker daemon must be running in order to download the DAR1 image and to start up a container
(2) Get the DAR1_docker image.
using the command line, run
docker pull birdy1123/dar1
If you go to the "Images" tab in the docker desktop UI, you should see "birdy1123/DAR1_docker"
(3) Run a container based on the DAR1_docker image
using the command line, run
docker run -it birdy1123/dar1
this runs the container in interactive mode (
-i
) with terminal access (-t
)you should see the prompt change to
root@some-number:/dar_one_docker#
once the container is running, you can also connect to a new bash terminal inside the container using the command
docker exec -it container_id /bin/bash
. The container id can be found in the Docker desktop app or the "some-number" that appears in the previous bullet point.
You're now ready for the beginner tutorial!
Setting up on local machine
You will need to clone 3 git repositories
- DAR1
- darwin3
- daroneconfig
First, we will clone the DAR1 code.
git clone https://github.com/barbara42/Dar_One.git
Then in a directory of your choosing, clone the MITgcm Darwin code. I put this in a folder called "climate_models" on my desktop.
git clone https://github.com/darwinproject/darwin3.git
Once darwin3 code is cloned, we will navigate to the /verification
folder underneath it.
cd darwin3/verification
Here, under darwin3/verification
, we will clone the dar_one_config
repository.
git clone https://github.com/barbara42/dar_one_config.git
After these steps, you should have
- the DAR1 source code
- the darwin3 source code
- the
dar_one_config
code nested underdarwin3/verification
Dependencies
In order to build and run the MITgcm on your machine, you need to have the following installed as well
- gfortran
- netcdf
For the Julia code, you will need to install julia and the following packages
- OrderedCollections
- Suppressor
- ClimateModels
- NCDatasets
The Julia dependencies are also listed in the file at the top level of Dar_One/packages.jl
. You can automatically install the Julia dependencies by running julia packages.jl
.
If you get errors when building the model, see the MITgcm getting started guide to help troubleshoot.
You can also see the dockerfile used here
FROM --platform=linux/amd64 ubuntu:latest
WORKDIR /dar_one_docker
COPY . .
RUN apt-get update -y
RUN apt-get install wget -y
RUN apt-get install vim -y
# download, install, and link julia
RUN wget https://julialang-s3.julialang.org/bin/linux/x64/1.8/julia-1.8.2-linux-x86_64.tar.gz
RUN tar zxvf julia-1.8.2-linux-x86_64.tar.gz
ENV PATH="${PATH}:/dar_one_docker/julia-1.8.2/bin"
# install julia packages
RUN julia packages.jl
# other dependencies
RUN apt-get install -y gfortran make
RUN apt-get install -y python-is-python3
# future: try netcdf-bin instead? does it still work?
RUN apt-get install -y libnetcdff-dev
Workflow
For more in-depth instructions, check out the beginner tutorials
In general, experiments with DAR1 are divided into two main steps
- Building
- grid size
- nutrient cycling
- Running
- set up experiment config
- initialize parameters
I like to separate these out into two scripts because the build step only has to be done once for each experiment setup. After you settle on what grid size to use (classically 1x1) and what nutrient setup (classically freely cycling, can also be set to constant available nutrients), you can modify all other parameters without having to re-build.
I recommend creating a folder at the top level of the Dar_One
directory with the name your-name-experiments
, and putting all scripts you create in there.
For every DAR1 script, you will first import DarOneTools.
include("../src/DarOneTools.jl")
using .DarOneTools
Next you must always make sure you have a line specifying the correct value for MITgcm_path[1]
. If you are using the docker, it will be set to "/daronedocker/darwin3". Otherwise, you will point it to the direcotry of darwin3 on your local machine.
# the path to the Darwin version of the MITgcm
MITgcm_path[1] = "/dar_one_docker/darwin3"
You build with the following function.
build(base_configuration)
Once the model has been built, you can run multiple experiments with different values for the intial parameters. I like to put the previous code in one file, and the code to initialize and run an experiment in another.
For the run script, you will also have to import DarOneTools and set the MITgcm path.
include("../src/DarOneTools.jl")
using .DarOneTools
# the path to the Darwin version of the MITgcm
MITgcm_path[1] = "/dar_one_docker/darwin3"
Set up experiment config id
config_id = "unique-experiment-name" # CHANGE ME
config_obj, rundir = create_MITgcm_config(config_id)
setup(config_obj)
The next step is to modify parameters (in-depth descriptions in beginnger tutorial). For modifying parameters, you will need to pass the config_obj
to each update function.
Then run the model.
run(config_obj)
To recap the basic workflow:
- Always import
DarOneTools
and setMITgcm_path
- Build
- set your grid size
- set nutrients to cycle or stay constant
- build
- Run
- setup experiment config
- modify parameters
- run